Git branches and worktrees in VS Code
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Git branches and worktrees in VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders Create and switch branches, set aside unfinished changes, and work on multiple branches in separate folders with the Git tools in VS Code.
Choose the workflow for your task: Use branches to keep separate lines of development and switch between them in one folder. Use a stash to set aside uncommitted changes without creating a commit. Use worktrees to keep multiple branches checked out in separate folders at the same time. Working with branches Branches are lightweight, movable pointers to specific commits in your Git history. Create a branch to develop a feature independently, then merge it into a target branch when the work is ready.
View current branch The current branch appears in several places in VS Code: Status Bar : shows the current branch name and provides quick branch switching Repositories view : displays the current branch in the repository header Source Control Graph : visually represents branch relationships and history Switch between branches Switching to a different branch is called "checking out" a branch in Git terminology. When you check out a branch, Git updates your working directory to match that branch's state.
To switch to a different branch: Select the branch name in the Status Bar, or run the Git: Checkout to command from the Command Palette ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ). Choose from the list of available branches: Local branches : Branches that exist on your local machine Remote branches : Branches from the remote repository that you can check out locally Recent branches : Recently used branches Tip If you have uncommitted changes when switching branches, Git might prevent the switch to avoid losing work.
Consider committing your changes or using a stash before switching. Create new branches To create a branch from your current commit ( HEAD ): Run Git: Create Branch... from the Command Palette ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ). Enter a name for your new branch. Use descriptive names like feature/user-authentication or bugfix/login-error . To start from a different branch or tag: Run Git: Create Branch From... from the Command Palette.
Select the source branch or tag, such as main or origin/main . Enter the new branch name. Both commands switch to the new branch after creation. You can also select the branch name in the Status Bar and choose Create new branch... or Create new branch from... . VS Code can generate random branch names. Configure this with the git.branchRandomName.enable Open in VS Code Open in VS Code Insiders and git.branchRandomName.dictionary Open in VS Code Open in VS Code Insiders settings.
Tip If you use the GitHub Pull Requests and Issues extension, you can create branches directly from GitHub issues, which gets you started working in a new local branch and automatically prefills the pull request for you. Rename and delete branches To rename the current branch: Run Git: Rename Branch from the Command Palette or select it from the More Actions (...) menu. Enter the new branch name. To delete a branch: Switch to a different branch (you can't delete the currently active branch).
Run Git: Delete Branch from the Command Palette or select it from the More Actions (...) menu. Select the branch to delete from the list. You can also delete a remote branch by using the matching Delete Remote Branch action. Caution Deleting a branch permanently removes it from your local repository. Make sure the branch has been merged or you no longer need the changes. Merge and publish branches When your feature is complete, merge it back into the main branch: Switch to the target branch (usually main or develop ).
Run Git: Merge... from the Command Palette. Select the branch to merge. To publish a branch to your remote repository, use the Publish Branch action. VS Code shows the merge result in the Source Control view. If there are conflicts, VS Code highlights them and provides tools to resolve them. Learn more about resolving merge conflicts . Manage stashes A Git stash temporarily stores selected uncommitted changes. Use a stash when you need to switch branches or handle another task without creating a commit for unfinished work.
You can invoke stash commands from the Command Palette or from the More Actions (...) menu in the Source Control view. Create a stash To stash your current changes: Open the Command Palette ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ). Run one of the following commands: Git: Stash to store tracked changes. Git: Stash (Include Untracked) to also store new, untracked files. Git: Stash Staged to store only the changes in the Staged Changes section.
This command requires Git 2.35 or later. Enter an optional message that describes the stashed work. Git stores the selected changes and removes them from the working directory. Changes outside the chosen scope remain: for example, Git: Stash leaves untracked files in place, and Git: Stash Staged leaves unstaged changes. View and restore stashed changes Run Git: View Stash from the Command Palette to inspect the files in a stash before restoring it.
To restore stashed changes, choose one of these commands from the Command Palette or the More Actions (...) menu: Git: Apply Stash... restores a selected stash and keeps it in the stash list. Git: Pop Stash... restores a selected stash and removes it from the stash list. Git: Apply Latest Stash or Git: Pop Latest Stash performs the corresponding action on the most recent stash. If the stashed changes conflict with changes in your working directory, resolve the conflicts before continuing.
Learn more about resolving merge conflicts . Delete stashes Run Git: Drop Stash... to permanently delete a selected stash, or run Git: Drop All Stashes... to delete every stash in the repository. Caution Dropping a stash is difficult to undo. Verify that you no longer need the changes before you delete it. Working with Git worktrees Use Git worktrees to work on another branch without changing the files or unfinished work in your current folder.
Understanding worktrees A Git repository normally has one working directory, called the primary worktree. A linked worktree is another working directory for the same repository. Each worktree checks out a branch in its own folder, so you can work on multiple branches at the same time without switching the files in your primary worktree. The following table shows how the Git concepts relate: Concept What it represents Repository The shared Git history, branches, tags, and remotes.
Branch A movable pointer to a commit in the repository history. Worktree A working directory with its own checked-out files, staging area, and uncommitted changes. Worktrees share the repository history, but they don't share working files or uncommitted changes. Git also prevents the same local branch from being checked out in more than one worktree at a time. For example, your primary worktree might have main checked out while a linked worktree contains the feature/theme-toggle branch.
To bring work back to main , merge the feature branch's commits or migrate its uncommitted changes . Worktrees are especially useful to: Develop multiple features in separate folders. Run different versions of an application side by side. Compare implementations across branches. Keep changes from parallel agent sessions separate. Create a worktree To create a new worktree in VS Code: Open the Source Control Repositories view from the Source Control view.
Select your repository, open the More Actions (...) menu, and choose Worktrees > Create Worktree . Follow the prompts to choose a branch and location for the new worktree. VS Code creates a new fol
The rest of this page is on the live site.