Activate custom aliases in VSCode automatically

[tomschr]

Situation

When opening a new terminal under VSCode, it sources .venv/bin/activate and activates the virtual Python environment. However, we need to manually source our own aliases. This is a bit inconvenient as you don't have access to these aliases (and neither your AI bot has that).

Proposed solution

This fix activates our own custom aliases in devel/activate-aliases.sh. It works for Linux and MacOS.

Alternatives

An alternative way would be to create a docbuild.code-workspace file and add the additions under a settings key. That may be even the more portable solution.

[github-actions]

Coverage Report

For commit 89eabb8

Click to expand Coverage Report

  Name                                           Stmts   Miss Branch BrPart  Cover
  --------------------------------------------------------------------------------
+ src/docbuild/models/deliverable.py               180      1     22      0  99.5%
+ src/docbuild/cli/cmd_check/process.py             58      0     22      1  98.8%
+ src/docbuild/models/manifest.py                  111      1     12      1  98.4%
+ src/docbuild/utils/pidlock.py                     79      1     14      1  97.8%
+ src/docbuild/cli/cmd_config/list.py               26      0      8      1  97.1%
+ src/docbuild/cli/cmd_validate/process.py         178      5     52      4  96.1%
+ src/docbuild/cli/callback.py                      35      0     10      2  95.6%
+ src/docbuild/utils/concurrency.py                 69      3     18      1  95.4%
+ src/docbuild/cli/cmd_cli.py                      110      3     16      3  95.2%
- src/docbuild/config/xml/stitch.py                 47      5     12      0  88.1%
- src/docbuild/cli/cmd_metadata/metaprocess.py     215     26     66     13  82.6%
- src/docbuild/cli/cmd_config/validate.py           21      2     12      3  78.8%
- src/docbuild/cli/cmd_check/__init__.py            18      5      2      0  65.0%
- src/docbuild/cli/cmd_build/__init__.py            13      5      0      0  61.5%
- src/docbuild/cli/cmd_metadata/__init__.py         27     10      2      0  58.6%
  --------------------------------------------------------------------------------
+ TOTAL                                           3068     67    746     30  97.0%
  
  47 files skipped due to complete coverage.

[tomschr]

I observed some strange behavior, so I'm a bit hesitant to merge it. Maybe further testing is required.

[sushant-suse]

I observed some strange behavior, so I'm a bit hesitant to merge it. Maybe further testing is required.

Hi Toms, that's strange. Can you please share some of your findings, maybe I can test it again and see what can be the root cause?

Thanks!

[tomschr]

Can you please share some of your findings, maybe I can test it again and see what can be the root cause?

Ok, I did this:

1. Switched my local Git repo to this branch.
2. Opened a new terminal with the menue "Terminal" > "New Terminal".
   My regular default prompt is shown (✔ ~/repos/GH/opensuse/docbuild [toms/vscode-acivate-aliases|…6⚑ 40]
3. It takes quite a few seconds (~5-10s?) until our custom aliases are sourced. After the time, the prompt changes to (docbuild) ✔ ~/repos/GH/opensuse/docbuild [toms/vscode-acivate-aliases|…6⚑ 40] which is okay.

The pause is irritating and noticable. I'm not sure why it takes so long. 🤔 Maybe it's my VSCode instance.

[sushant-suse]

Can you please share some of your findings, maybe I can test it again and see what can be the root cause?

Ok, I did this:

1. Switched my local Git repo to this branch.
2. Opened a new terminal with the menue "Terminal" > "New Terminal".
   My regular default prompt is shown (✔ ~/repos/GH/opensuse/docbuild [toms/vscode-acivate-aliases|…6⚑ 40]
3. It takes quite a few seconds (~5-10s?) until our custom aliases are sourced. After the time, the prompt changes to (docbuild) ✔ ~/repos/GH/opensuse/docbuild [toms/vscode-acivate-aliases|…6⚑ 40] which is okay.

The pause is irritating and noticable. I'm not sure why it takes so long. 🤔 Maybe it's my VSCode instance.

You aren't imagining things, Toms. I think that 5-10 second pause is a real bug, and I tracked down exactly why it's happening (maybe I am right).

It comes down to unset PROMPT_COMMAND. VS Code relies on a hidden background script (Shell Integration) that tracks the state of the command prompt. The Python extension waits for a "ready" signal from this script before auto-injecting the .venv activation. Because I unset the command entirely, the Python extension never gets that signal, waits until a built-in timeout (~5-10 seconds), and finally gives up to force-activate the environment.

Instead of unsetting the command, we can use a sentinel environment variable as a flag so it only sources the file once, and then we append the original $PROMPT_COMMAND so VS Code's internal scripts continue running smoothly.

Here is the updated configuration for .vscode/settings.json:

    "terminal.integrated.env.linux": {
        "PROMPT_COMMAND": "if [ -z \"$DOCBUILD_ALIASES_LOADED\" ] && [ -f \"${workspaceFolder}/devel/activate-aliases.sh\" ]; then export DOCBUILD_ALIASES_LOADED=1; source \"${workspaceFolder}/devel/activate-aliases.sh\"; fi; $PROMPT_COMMAND"
    },
    "terminal.integrated.env.osx": {
        "PROMPT_COMMAND": "if [ -z \"$DOCBUILD_ALIASES_LOADED\" ] && [ -f \"${workspaceFolder}/devel/activate-aliases.sh\" ]; then export DOCBUILD_ALIASES_LOADED=1; source \"${workspaceFolder}/devel/activate-aliases.sh\"; fi; $PROMPT_COMMAND"
    }

Regarding your alternative suggestion of using a docbuild.code-workspace file: that is a great option if we ever move to a multi-root workspace setup! However, it actually uses the exact same environment injection logic under the hood as settings.json, so it wouldn't have bypassed this specific timeout bug.

Let me know if you are able to test this new version and if the prompt loads instantly for you now?
Thanks.

[tomschr]

I've tried your settings. When I paste that into the project's root .vscode/settings.json, VSCode says:

This setting cannot be applied in this workspace.
It will be applied when you open the containing workspace folder directly.

[sushant-suse]

I've tried your settings. When I paste that into the project's root .vscode/settings.json, VSCode says:

This setting cannot be applied in this workspace.
It will be applied when you open the containing workspace folder directly.

Ah, that warning explains a lot Toms. That is VS Code's security and scoping engine stepping in.

Whenever VS Code thinks it is running in a multi-root workspace context (or if the folder isn't opened completely standalone), it explicitly restricts and ignores terminal.integrated.env.* settings inside the folder-level .vscode/settings.json. It does this to prevent one sub-folder from silently hijacking the terminal environment variables for the entire window.

This means your alternative idea was the correct path all along! If we move this to a docbuild.code-workspace file, it elevates the setting to the "Workspace level," which VS Code fully trusts and applies instantly.

Can you try this?

{
    "folders": [
        {
            "path": "."
        }
    ],
    "settings": {
        "terminal.integrated.env.linux": {
            "PROMPT_COMMAND": "if [ -z \"$DOCBUILD_ALIASES_LOADED\" ] && [ -f \"${workspaceFolder}/devel/activate-aliases.sh\" ]; then export DOCBUILD_ALIASES_LOADED=1; source \"${workspaceFolder}/devel/activate-aliases.sh\"; fi; $PROMPT_COMMAND"
        },
        "terminal.integrated.env.osx": {
            "PROMPT_COMMAND": "if [ -z \"$DOCBUILD_ALIASES_LOADED\" ] && [ -f \"${workspaceFolder}/devel/activate-aliases.sh\" ]; then export DOCBUILD_ALIASES_LOADED=1; source \"${workspaceFolder}/devel/activate-aliases.sh\"; fi; $PROMPT_COMMAND"
        }
    }
}

Let me know if this helped.