To maintain separate command histories for distinct Visual Studio Code workspaces, configure the integrated terminal to use a dynamic
HISTFILE variable. This is achieved by setting
terminal.integrated.env.linux (or
terminal.integrated.env.osx) in your workspace settings to export
HISTFILE based on the current folder path. This ensures that command history remains isolated per project, preventing clutter and context switching errors across different development environments.
Understanding the Problem with Shared History
By default, the Bash shell writes all executed commands to a single file, typically located at
~/.bash_history. When you open multiple projects in Visual Studio Code, especially if they share the same user account, the integrated terminal will append commands from Project A and Project B into this same file. This creates several issues:
- Context Confusion: Pressing the up arrow key might reveal commands relevant to an old project while you are working on a new one.
- Cleanup Difficulty: You cannot easily delete history for just one project without risking the loss of commands from others.
- Security Risks: If one project contains sensitive API keys or passwords in commands, those secrets become mixed with general commands from other projects.
While some developers prefer using Zsh with plugins like
How to Make ZSH Navigation More Like Bash to manage complex state, Bash users can achieve similar isolation through environment variable manipulation within VS Code’s configuration.
Configuring Workspace-Specific Environment Variables
The most robust method to solve this is by instructing the integrated terminal to set the
HISTFILE environment variable dynamically when it starts. VS Code allows you to define environment variables specifically for a workspace, overriding global defaults.
First, open the specific workspace you wish to isolate. Then, access the settings interface by pressing
Ctrl+Shift+P (or
Cmd+Shift+P on macOS) and selecting "Preferences: Open Workspace Settings (JSON)". This opens the
.vscode/settings.json file for that specific project.
You need to add a configuration block that targets the Linux or macOS terminal environments. Note that Windows uses a different mechanism via
terminal.integrated.env.windows, but the principle remains the same. For Linux and macOS, use the following structure:
{
"terminal.integrated.env.linux": {
"HISTFILE": "${workspaceFolder}/.bash_history"
},
"terminal.integrated.env.osx": {
"HISTFILE": "${workspaceFolder}/.bash_history"
}
}
Here,
${workspaceFolder} is a built-in VS Code variable that resolves to the absolute path of the root directory of your current workspace. By pointing
HISTFILE to a file inside the project directory (e.g.,
.bash_history), each workspace gets its own unique history file.
Why Use Workspace Settings Instead of User Settings?
It is critical to apply this configuration in the workspace settings rather than the user settings. If you place this in your global
settings.json, every new terminal instance across all your projects will attempt to write to the same local
.bash_history file, which defeats the purpose of isolation. Workspace settings ensure that only the specific project directory triggers this behavior.
Handling Existing History Files
Once you have applied the configuration, existing commands in your global
~/.bash_history will not automatically migrate. You may want to clean up your global history to remove noise from previous sessions.
If you wish to merge important commands from the global history into your new workspace-specific history, you can do so manually. However, for most developers, starting fresh is cleaner. You can truncate the global history file by running:
echo "" > ~/.bash_history
After this, restart your VS Code integrated terminals. New commands typed in the terminal belonging to the configured workspace will now be saved exclusively to
<project_root>/.bash_history. Commands in other terminals that do not have this configuration will continue to use the global
~/.bash_history.
Verifying the Configuration
To ensure the setup is working correctly, follow these steps:
- Open a new integrated terminal in the configured workspace.
- Type a test command, such as
echo "test_workspace_history".
- Close the terminal completely. VS Code must close the shell process to flush the history buffer to disk.
- Navigate to your project root directory in your system file explorer.
- Check for the existence of the
.bash_history file.
- Open the file and verify that your test command is present.
If the file does not appear, check the VS Code output panel. Switch the dropdown from "Log (Window)" to "Terminal" to see any error messages related to environment variable expansion. Common issues include typos in the JSON syntax or incorrect casing of
linux vs
Linux (VS Code settings are case-sensitive).
For more advanced terminal customizations, you might also look into
Different Bash History per VS Code Workspace: How to Set It Up, which covers alternative approaches using shell profiles.
Troubleshooting Common Issues
Sometimes the history file may not update immediately due to how Bash buffers writes. Bash typically writes history to disk when the shell exits. If you kill the terminal abruptly using the stop button in VS Code, the last few commands might be lost. To mitigate this, consider adding
shopt -s histappend to your
~/.bashrc to ensure history is appended rather than overwritten, though this primarily affects the target file specified by
HISTFILE.
Additionally, if you are using Git Bash on Windows, the environment variable name might differ slightly depending on your shell type. Ensure you are targeting the correct OS profile in your VS Code settings. For cross-platform consistency, you can specify both
linux,
osx, and
windows keys in the same JSON object, mapping each to the appropriate local history file path.
Frequently Asked Questions
Will this affect my global bash history?
No, configuring
HISTFILE in workspace settings only redirects where new commands are stored for terminals spawned in that specific workspace. Your global
~/.bash_history remains untouched and continues to function for terminals outside the configured workspace.
Can I use this method for Zsh shells?
Yes, the principle is identical. Instead of
HISTFILE, you would set
ZSH_HISTORY_FILE or simply override
HISTFILE if your Zsh configuration respects it. Many Zsh setups use
HISTFILE directly, making the VS Code configuration approach transferable with minimal adjustment.
What happens if I rename the project folder?
Since the history file path is tied to
${workspaceFolder}, renaming the folder moves the
.bash_history file along with it. The relative path remains valid, so your history continuity is preserved even if you move the entire project directory within your filesystem.
Does this work for remote SSH workspaces?
Yes, provided the remote server uses Bash and VS Code properly injects environment variables into the remote terminal session. The
${workspaceFolder} variable resolves to the path on the remote machine, ensuring the history file is created in the correct location on the server.
How do I clear the history for just one workspace?
Simply delete the
.bash_history file located in the root of that workspace folder. Since it is isolated from your global history, removing it will not affect your commands in other projects. You can automate this cleanup with a simple script if needed.