From c9e51a9e55ff64a077835e9c002beb4009aeeb7a Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Wed, 19 Nov 2025 13:24:16 +0100 Subject: [PATCH 01/12] Restructure source control overview article --- docs/sourcecontrol/images/overview/diff.png | 4 +- .../images/overview/gitbranches.png | 4 +- docs/sourcecontrol/images/overview/gutter.png | 4 +- .../overview/incoming-outgoing-changes.png | 4 +- .../images/overview/overview.png | 4 +- .../images/overview/source-control-graph.png | 3 + .../images/overview/stage-changes.png | 4 +- .../images/overview/timeline-view.png | 4 +- .../images/overview/worktree-create.png | 4 +- docs/sourcecontrol/overview.md | 432 +++--------------- 10 files changed, 93 insertions(+), 374 deletions(-) create mode 100644 docs/sourcecontrol/images/overview/source-control-graph.png diff --git a/docs/sourcecontrol/images/overview/diff.png b/docs/sourcecontrol/images/overview/diff.png index 48ca28e535..89b6fea5fb 100644 --- a/docs/sourcecontrol/images/overview/diff.png +++ b/docs/sourcecontrol/images/overview/diff.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:6d48169415d937b2effe8907dd5e241efda94ef1099386092972f199c85b620d -size 20852 +oid sha256:7457cf8aebfaab9d3ef3bf34ae092243659bbabaa541ae35a4137925dba6909f +size 121978 diff --git a/docs/sourcecontrol/images/overview/gitbranches.png b/docs/sourcecontrol/images/overview/gitbranches.png index 7e7ce09a81..b86dc1faf8 100644 --- a/docs/sourcecontrol/images/overview/gitbranches.png +++ b/docs/sourcecontrol/images/overview/gitbranches.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:9e310a642afd98b11a9c563ddc0b7c1a8814ccce870353cf08be5fd31f0e4b3d -size 10265 +oid sha256:c3e32e2f063f110d4b4a61e6f82582523f42af63c53ffcabbb54b260b6a21a61 +size 73484 diff --git a/docs/sourcecontrol/images/overview/gutter.png b/docs/sourcecontrol/images/overview/gutter.png index d1f8d805b8..c7a2f04db4 100644 --- a/docs/sourcecontrol/images/overview/gutter.png +++ b/docs/sourcecontrol/images/overview/gutter.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:9041d04f64a246c4230c23a9536973b203a8d5f8c37dd8071f2bd1a620533355 -size 5534 +oid sha256:fae00e221043da0ce1262f075d89b9bf7243accd1b3a098bf6305fda4def88a8 +size 105551 diff --git a/docs/sourcecontrol/images/overview/incoming-outgoing-changes.png b/docs/sourcecontrol/images/overview/incoming-outgoing-changes.png index 186dcc44c9..5f9f1d6b15 100644 --- a/docs/sourcecontrol/images/overview/incoming-outgoing-changes.png +++ b/docs/sourcecontrol/images/overview/incoming-outgoing-changes.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:90a1b53925ea68248d1c847cb0d005dba9ec766e7054e080faacc7004f72d25c -size 251174 +oid sha256:1a6fab3c6ade72e13e5e5ff90b4ef7f55c4523919819e1e433e1508eb423d0cf +size 39756 diff --git a/docs/sourcecontrol/images/overview/overview.png b/docs/sourcecontrol/images/overview/overview.png index 35407cf6ce..f2caeb0993 100644 --- a/docs/sourcecontrol/images/overview/overview.png +++ b/docs/sourcecontrol/images/overview/overview.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:f8f88152f3f6591934f9c04409c8d0b05c8fa5addbe3aff30ca19da490b70158 -size 48521 +oid sha256:7ed132d944db819f84b355e447b131ab02a402ac2b79aacafe14d3af4b3f2c58 +size 173464 diff --git a/docs/sourcecontrol/images/overview/source-control-graph.png b/docs/sourcecontrol/images/overview/source-control-graph.png new file mode 100644 index 0000000000..0c4d85a776 --- /dev/null +++ b/docs/sourcecontrol/images/overview/source-control-graph.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cd509d4705d06a50628c3276ff95404776bb7670a1f312a92062e5a121d7ce65 +size 105377 diff --git a/docs/sourcecontrol/images/overview/stage-changes.png b/docs/sourcecontrol/images/overview/stage-changes.png index 2dc4197e5b..1db2e9d07d 100644 --- a/docs/sourcecontrol/images/overview/stage-changes.png +++ b/docs/sourcecontrol/images/overview/stage-changes.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:873531f7064dd2cc5503800172ce3b7be9c7a19a292dad5acf5ce41e32925aec -size 19093 +oid sha256:3350f26e1a616c7ccba7f24924582bcfa793de59c61addc00f10a6b4e31169c8 +size 67838 diff --git a/docs/sourcecontrol/images/overview/timeline-view.png b/docs/sourcecontrol/images/overview/timeline-view.png index b7522c0a6b..2bb55640db 100644 --- a/docs/sourcecontrol/images/overview/timeline-view.png +++ b/docs/sourcecontrol/images/overview/timeline-view.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:a655e9d727b5aba7b06bcc5f3ddfa39ab0fc81304891e4691819c0141f60fbec -size 22539 +oid sha256:e52c12f2b451a831cf746498397d752dd0f6ed0ce6ebd6dd5d0b2d177dd3337c +size 302388 diff --git a/docs/sourcecontrol/images/overview/worktree-create.png b/docs/sourcecontrol/images/overview/worktree-create.png index 2a128dfeec..0ea1f9f32a 100644 --- a/docs/sourcecontrol/images/overview/worktree-create.png +++ b/docs/sourcecontrol/images/overview/worktree-create.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:af435af5d778a5e4c894fdce82f8cff158247b49faaa74504cb9ac02cbbb92bf -size 103695 +oid sha256:2b6028dfa2d70db01d571df5dd4295397bfd548faa4fd652dd15e24a2612bcb2 +size 102735 diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index cc2d7d0b9d..c57024beac 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -1,432 +1,148 @@ --- ContentId: 7E22CCC0-2AB8-4729-A4C9-BE2B16853820 DateApproved: 11/12/2025 -MetaDescription: Visual Studio Code source control management with integrated Git support. +MetaDescription: Learn how to use VS Code's integrated Git source control features like staging, committing, branching, merge conflict resolution, and GitHub integration. --- -# Using Git source control in VS Code +# Source Control in VS Code -Visual Studio Code has integrated source control management (SCM) and includes [Git](https://git-scm.com/) support out-of-the-box. Many other source control providers are available through extensions on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=SCM%20Providers&sortBy=Installs). +Visual Studio Code has integrated source control management (SCM) that lets you work with Git and other version control systems directly in your editor. Git support is built-in, and you can install extensions for other SCM providers from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/search?target=VSCode&category=SCM%20Providers&sortBy=Installs). -With GitHub Copilot in VS Code, you can get suggestions for commit messages, pull requests, and review code changes before committing them. Learn more about [GitHub Copilot in VS Code](/docs/copilot/overview.md). +The integrated source control interface provides access to Git functionality through a graphical interface instead of terminal commands. You can perform Git operations like staging changes, committing files, creating branches, and resolving merge conflicts without switching to the command line. -> [!TIP] -> If you don't have a Copilot subscription yet, use Copilot for free by signing up for the [Copilot Free plan](https://github.com/github-copilot/signup). You'll get a monthly limit of completions and chat interactions. +Changes you make in the VS Code interface are synced with your command-line Git operations, so you can use both the UI and terminal as needed. The source control interface works alongside the command line rather than replacing it. -> [!TIP] -> If you're just getting started with Git, the [git-scm](https://git-scm.com/doc) website is a good place to start, with a popular online [book](https://git-scm.com/book), Getting Started [videos](https://git-scm.com/video/what-is-git) and [cheat sheets](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf). The VS Code documentation assumes you are already familiar with Git. - -## Working in a Git repository - -VS Code recognizes when you open a folder that is a Git repository. The Source Control view enables you to perform most of the Git operations without using the command line. - -> [!IMPORTANT] -> **Make sure that Git is installed on your machine.** VS Code uses your machine's Git installation (at least version `2.0.0`), so you need to [install Git](https://git-scm.com/download) first before you get these features. - -You can access the Source Control view from the by selecting the **Source Control** icon in the Activity Bar or by using the `kb(workbench.view.scm)` keyboard shortcut. If you have changes, the Source Control icon indicates **how many changes** you currently have in your repository. - -The Source Control view shows the details of your current repository changes: **CHANGES**, **STAGED CHANGES** and **MERGE CHANGES**. You can also view the [**source control graph**](#source-control-graph) to see how your changes relate to the repository's history. - -![Overview of Git](images/overview/overview.png) - -When you select a file in the Source Control view, you will see the changes that you have made to that file in a diff editor. - -> [!TIP] -> For unstaged changes, the editor on the right still lets you edit the file: feel free to use it! - -You can also find indicators of the **status of your repository** in the bottom-left of the VS Code Status Bar: the **current branch**, **dirty indicators**, and the number of **incoming and outgoing commits** of the current branch. To **check out** any branch in your repository, select the status indicator and select the Git reference from the list. - -> [!TIP] -> You can open VS Code in a sub-directory of a Git repository. VS Code's Git services will still work as usual, showing all changes within the repository, but file changes outside of the scoped directory are shaded with a tool tip indicating they are located outside the current workspace. - -## Cloning a repository - -If you haven't opened a folder yet, the Source Control view will give you the options to **Open Folder** from your local machine or **Clone Repository**. - -![First run Source Control experience](images/overview/firstrun-source-control.png) +## Prerequisites -If you select **Clone Repository**, you will be asked for the URL of the remote repository (for example on [GitHub](https://github.com/)) and the parent directory under which to put the local repository. +To use Git features in VS Code, you need: -For a GitHub repository, you would find the URL from the GitHub **Code** dialog. +* VS Code uses your machine's Git installation. [Install Git version 2.0.0.0 or later](https://git-scm.com/download) on your machine. -![clone repository dialog](images/overview/GitHub-clone-dialog.png) +* When you commit changes, Git uses your configured username and email. You can set these values with: -You would then paste that URL into the **Git: Clone** prompt. - -![set repository URL](images/overview/set-repo-URL.png) - -You'll also see the option to **Clone from GitHub**. Once you authenticate with your GitHub account in VS Code, you'll be able to search through repositories by name, and select any repo to clone it. You can also start the flow to clone a Git repository with the **Git: Clone** command in the **Command Palette** (`kb(workbench.action.showCommands)`). To see a step-by-step walkthrough, check out our [Clone repos from VS Code](https://www.youtube.com/watch?v=bz1KauFlbQI) video. - -> [!NOTE] -> If you'd like to work on a repository without cloning the contents to your local machine, you can install the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=github.remotehub) extension to browse and edit directly on GitHub. You can learn more in the [GitHub Repositories extension](/docs/sourcecontrol/github.md#github-repositories-extension) section. - -## Initialize a repository - -If your workspace is on your local machine, you can enable Git source control by creating a Git repository with the **Initialize Repository** command. When VS Code doesn't detect an existing Git repository, the Source Control view will give you the options to **Initialize Repository** or **Publish to GitHub**. - -![Git initialize repository](images/overview/initialize-repository.png) - -You can also run the **Git: Initialize Repository** and **Publish to GitHub** commands from the **Command Palette** (`kb(workbench.action.showCommands)`). - -- **Initialize Repository**: creates the necessary Git repository metadata files and shows your workspace files as untracked changes ready to be staged. -- **Publish to GitHub**: directly publishes your workspace folder to a GitHub repository, allowing you to choose between private and public repositories. Check out our [publishing repos](https://www.youtube.com/watch?v=3BBvBwDW4CY) video for more information about publishing to GitHub. - -## Commit - -**Staging** (`git add`) and **unstaging** (`git reset`) can be done via contextual actions in the files or by drag-and-drop. - -> [!NOTE] -> **Configure your Git username and email.** When you commit, be aware that if your username and/or email is not set in your Git configuration, Git will fall back to using information from your local machine. You can find the details in [Git commit information](https://git-scm.com/docs/git-commit#_commit_information). - -![Stage all changes button](images/overview/stage-changes.png) - -You can type a commit message above the changes and press `kbstyle(Ctrl+Enter)` (macOS: `kbstyle(⌘+Enter)`) to commit them. If there are any staged changes, only those changes will be committed. Otherwise, you'll get a prompt asking you to select what changes you'd like to commit and get the option to change your commit settings. - -We've found this to be a great workflow. For example, in the earlier screenshot, only the staged changes to `overview.png` will be included in the commit. Later staging and commit actions could include the changes to `versioncontrol.md` and the two other `.png` images as a separate commit. - -More specific **Commit** actions can be found in the **Views and More Actions** `...` menu on the top of the Source Control view. - -![views and more actions button](images/overview/scm-more-actions.png) + ```bash + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` > [!TIP] -> If you commit your change to the wrong branch, undo your commit using the **Git: Undo Last Commit** command in the **Command Palette** (`kb(workbench.action.showCommands)`). - - +> If you're new to Git, the [git-scm](https://git-scm.com/doc) website is a good place to start, with a popular online [book](https://git-scm.com/book), Getting Started [videos](https://git-scm.com/video/what-is-git) and [cheat sheets](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf). -### Generate a commit message with AI +## Get started with a repository -GitHub Copilot in VS Code can generate a commit message for you, based on the code changes you've made. In the Source Control view, select the **Generate Commit Message with Copilot** button () in the commit message input box. +VS Code automatically detects when you open a folder that's a Git repository and activates all source control features. To get started with a new or existing repository, you have several options: -![Screenshot that shows the Generate Commit Message with Copilot button in the commit message input box.](images/overview/copilot-generate-commit-message.png) +* **Initialize a new repository**: Create a new Git repository for your current folder. -If you have specific requirements for your commit message for your organization or project, you can use Copilot custom instructions for generating commit messages. For example, _commit messages have a maximum length of 60 chars and should start with a verb in the present tense_. Get more details about [Copilot custom instructions for generating commit messages](/docs/copilot/customization/overview.md). +* **Clone a repository**: Clone an existing repository from GitHub or another Git host. -### Author commit messages using an editor - -If you don't enter a commit message when committing changes, VS Code opens an editor for the `COMMIT_EDITMSG` file where you can author the commit message in the editor. After you provide a commit message, either close the editor tab, or select the **Accept Commit Message** button in the editor toolbar to commit the changes. - -To cancel the commit operation, you can either clear the contents of the text editor and close the editor tab, or select the **Discard Commit Message** button in the editor toolbar. - -![Author commit message in a full text editor](images/overview/scm-git-editor.gif) - -You can disable this functionality by toggling the `setting(git.useEditorAsCommitInput)` setting. After the setting is changed, you have to restart VS Code for the change to take effect. - -To use the same flow for git commit commands executed in the integrated terminal, enable the `setting(git.terminalGitEditor)` setting. - -## Git blame information - -VS Code can show git blame information inline in the editor and in the Status Bar. Hover over the Status Bar item or inline hint to view detailed git blame information. - -To enable or disable git blame information, use the **Git: Toggle Git Blame Editor Decoration** and **Git: Toggle Git Blame Status Bar Item** commands, or configure these settings: - -- `setting(git.blame.statusBarItem.enabled)` (enabled by default) -- `setting(git.blame.editorDecoration.enabled)` - - - -You can customize the format of the message that is shown in the editor and in the Status Bar with the `setting(git.blame.editorDecoration.template)` and `setting(git.blame.statusBarItem.template)` settings. You can use variables for the most common information. - -For example, the following template shows the subject of the commit, the author's name, and the author's date relative to now: - -```json -{ - "git.blame.editorDecoration.template": "${subject}, ${authorName} (${authorDateAgo})" -} -``` - -To adjust the color of the editor decoration, use the `git.blame.editorDecorationForeground` theme color. - -## Review uncommitted code changes with AI - -GitHub Copilot in VS Code can help you review your uncommitted code changes. - -1. In the Source Control view, select the **Code Review** button to start a code review of the uncommitted changes - - ![Screenshot that shows the Code Review button in the Source Control view.](images/overview/copilot-code-review.png) - -1. Copilot generates code review comments and suggestions as overlays in the editor - - ![Screenshot that shows the code review comments generated by Copilot.](images/overview/copilot-code-review-results.png) - - You can also view a list of all code review comments in the **Comments** panel. - -1. You apply or discard suggestions by using the corresponding buttons, or context menu actions in the Comments panel - -Get more details about [reviewing code changes with Copilot](https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review?tool=vscode) in the GitHub documentation. - -## Branches and Tags - - - -You can create and checkout branches directly within VS Code through the **Git: Create Branch** and **Git: Checkout to** commands in the **Command Palette** (`kb(workbench.action.showCommands)`). - -If you run **Git: Checkout to**, you will see a dropdown list containing all of the branches or tags in the current repository. It will also give you the option to create a new branch if you decide that's a better option, or checkout a branch in detached mode. - -![Git checkout](images/overview/gitbranches.png) - -The **Git: Create Branch** command lets you quickly create a new branch. Just provide the name of your new branch and VS Code will create the branch and switch to it. If you choose to **Create new branch from...**, you'll get an extra prompt that allows you to specify which commit the new branch should be pointing to. +* **Open a remote repository**: Work with a repository without cloning it to your local machine with the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=github.remotehub) extension. > [!TIP] -> VS Code can automatically save and restore open editors when you switch to another branch. Use the `setting(scm.workingSets.enabled)` setting to enable this feature. To control the open editors when switching to a branch for the first time, you can use the `setting(scm.workingSets.default)` setting. - -## Worktrees +> You can publish a local repository directly to GitHub with the **Publish to GitHub** command, which creates a new repository and pushes your commits in one step. -VS Code has built-in support for [Git worktrees](https://git-scm.com/docs/git-worktree), making it easy to manage and work with multiple branches at the same time. +## Source control interface -> [!NOTE] -> You can disable automatic worktree detection by toggling the `setting(git.detectWorktrees)` setting. +VS Code provides Git functionality through several key interface elements. This UI integration enables you to perform Git operations without knowing terminal commands: -### Create a worktree +* **Source Control view**: central hub for common Git operations like staging, committing, and managing changes -You can create a new worktree directly from the **Source Control Repositories** view or by using the **Git: Create Worktree** command in the Command Palette (`kb(workbench.action.showCommands)`). + ![Screenshot of the Source Control view showing staged changes, and the diff editor showing side-by-side changes.](images/overview/overview.png) -1. In the Source Control view, select **...** > **Repositories** to open the Source Control Repositories view. +* **Source Control Graph**: graphical representation of your commit history and branch relationships - ![Screenshot that shows the Repositories option in the Source Control view.](images/overview/source-control-view-repositories.png) + ![Screenshot of the Source control graph showing commit history.](images/overview/source-control-graph.png) -1. Right-click on a repository, and select **Worktrees** > **Create Worktree...** +* **Diff editor**: side-by-side file comparisons for effective change review - ![Screenshot that shows the Create Worktree option in the context menu of a repository in the Source Control Repositories view.](images/overview/worktree-create.png) + ![Screenshot of the diff editor showing changes between file versions.](images/overview/diff.png) -1. Follow the prompts to choose a branch and location for the new worktree. +* **Additional UI elements**: in-context Git information like editor gutter indicators or Git blame annotations - VS Code creates a new folder for the worktree at the specified location and checks out the selected branch into that folder. + ![Screenshot of editor gutter indicators showing line changes and a hover showing Git blame information.](images/overview/gutter.png) - The Source Control Repositories view shows the newly created worktree under its parent repository. VS Code distinguishes between repositories, submodules, and worktrees, showing their relationships for better clarity. +If you prefer using the command line, you can still run Git commands in the integrated terminal (`kb(terminal.toggleTerminal)`). Changes made via the terminal are reflected in the VS Code source control interface. -### Open a worktree +## Common workflows -There are multiple ways to open a worktree: +### Review changes before committing -* Directly open the folder associated with the worktree in VS Code. VS Code automatically detects that it's a worktree of an existing repository. +Before committing changes, it's important to review them to ensure accuracy and quality. Use VS Code's AI features to perform a code review of your changes and get review comments and suggestions in the editor. -* Right-click the worktree in the Source Control Repositories view and select **Open Worktree in New Window** or **Open Worktree in Current Window**. +![Screenshot of the code review results, showing as editor overlay comments.](images/overview/copilot-code-review-results.png) -* Run the **Git: Open Worktree in Current Window** or **Git: Open Worktree in New Window** command in the Command Palette and select the desired worktree. +### Stage and commit changes -### Manage worktrees +Review your changes in the Source Control view, then stage files by selecting the **+** icon next to each file or stage all changes at once. For more fine-grained control, stage specific lines or selections from a file's diff view. -All detected worktrees are shown in the Source Control Repositories view, grouped under their parent repository. +![Screenshot of staging changes in the Source Control view.](images/overview/stage-changes.png) -When you select a worktree in the list, the Changes view shows the pending changes for that worktree. +Type your commit message in the input box or select the sparkle icon () in the commit message input box to use AI to generate a commit message based on your staged changes. -To delete a worktree, right-click it in the list and select **Delete Worktree**. Alternatively, run the **Git: Delete Worktree** command in the Command Palette. +![Screenshot of generating a commit message with Copilot.](images/overview/copilot-generate-commit-message.png) -### Compare and migrate changes from a worktree +### Sync with remotes -When you make changes in a worktree, you can compare those changes with your main workspace and bring worktree changes back into your main repository. +When your branch is connected to a remote branch, VS Code shows sync status in the Status Bar and shows incoming and outgoing commits in the Source Control view. You can quickly sync or perform individual fetch, pull, and push operations. -1. In the **Source Control** view, right-click a changed file in the worktree and select **Compare with Workspace** to see the differences side-by-side. +![Screenshot of the Source Control view showing the sync button indicating outgoing and incoming changes.](images/overview/incoming-outgoing-changes.png) - ![Screenshot that shows the Compare with Workspace option in the context menu of a changed file in a worktree.](images/overview/worktree-compare-changes.png) +### Resolve merge conflicts -1. After reviewing, use the **Migrate Worktree Changes...** command from the Command Palette to merge all changes from a worktree into your current workspace. +When you encounter merge conflicts, VS Code highlights the conflicting files in the Source Control view. Open a file with conflicts to see inline conflict markers. You have several options to resolve the conflicts: -## Remotes - -Given that your repository is connected to some remote and that your checked out branch has an [upstream link](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) to a branch in that remote, VS Code offers you useful actions to **push**, **pull**, and **sync** that branch (the latter will run a **pull** command followed by a **push** command). You can find these actions in the **Views and More Actions** `...` menu, along with the option to **add or remove a remote**. - -VS Code is able to periodically fetch changes from your remotes. This enables VS Code to show how many changes your local repository is ahead or behind the remote. This feature is disabled by default and you can use the `setting(git.autofetch)` [setting](/docs/configure/settings.md) to enable it. - -> [!TIP] -> You should [set up a credential helper](https://docs.github.com/get-started/getting-started-with-git/caching-your-github-credentials-in-git) to avoid getting asked for credentials every time VS Code talks to your Git remotes. If you don't do this, you may want to consider disabling automatic fetching via the `setting(git.autofetch)` [setting](/docs/configure/settings.md) to reduce the number of prompts you get. +* Use inline editor actions to choose how to resolve the conflicts directly in the editor +* Use the 3-way merge editor for a side-by-side view of changes and merge result +* Use AI assistance to help resolve merge conflicts -## Source control graph +![Screenshot of the 3-way merge editor.](images/overview/merge-editor-overview.png) -When you have a remote repository configured, you can see how many commits you are ahead or behind the remote. The **Graph** view in the Source Control view shows a graphical representation of the commits that are incoming and outgoing. +Once resolved, you can stage the files and commit the merge. -The graph contains the current branch, the current branch's upstream branch, and an optional base branch. The root of the graph is the common ancestor of these branches. +### Work with branches, worktrees, and stashes -![Source control view showing a graph visualization of the incoming and outgoing changes.](images/overview/incoming-outgoing-changes.png) +VS Code supports multiple workflows for managing parallel development work. You can easily switch between branches within a single workspace. -The graph provides the following functionality: +![Screenshot of the branch Quick Pick showing options to switch to a branch or create a new branch.](images/overview/gitbranches.png) -- Select an entry to see the files that are changed in that commit. Select the **Open Changes** action to see the diff of the commit in the editor. -- Right-click on a commit to perform actions such as checkout, cherry-pick, adding it as context to chat, and more. -- Select a file to see the diff of that file in the editor. +To work with multiple branches simultaneously, you can use Git worktrees to create separate working directories for different branches. -Use the actions in the Graph view tool bar to select the branch, fetch, pull, push, and sync changes. +![Screenshot of the worktrees submenu in the Source Control Repositories view.](images/overview/worktree-create.png) -## Git Status Bar actions +Temporarily save uncommitted changes when you need to switch contexts quickly by using a Git stash: save, view, apply, or pop your stashed changes directly from the Source Control view. -There is a **Synchronize Changes** action in the Status Bar, next to the branch indicator, when the current checked out branch has an upstream branch configured. **Synchronize Changes** will pull remote changes down to your local repository and then push local commits to the upstream branch. +### View commit history -![git status bar sync](images/overview/git-status-bar-sync.png) +It can be helpful to review the commit history to understand how your code has changed over time. -If there is no upstream branch configured and the Git repository has remotes set up, the **Publish** action is enabled. This will let you publish the current branch to a remote. +The Source Control Graph provides a visual representation of your branch structure and commit history, highlighting incoming and outgoing commits. -![git status bar publish](images/overview/git-status-bar-publish.png) +The Timeline view in the Explorer view shows the commit history for a specific file, allowing you to see how it has evolved. You can filter the timeline to show only Git commits or to also include local file changes. -If your workspace contains multiple Git repositories, the Status Bar will show the current repository. When you select the Status Bar item, you can choose the behavior of which repository should be active. +![Screenshot of the timeline view showing file commit history.](images/overview/timeline-view.png) -![git status bar repo name](images/overview/git-status-bar-repository.png) +## Working with GitHub -## Gutter indicators +VS Code integrates with GitHub to provide pull request and issue management directly in your editor. Install the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension to: -If you open a folder that is a Git repository and begin making changes, VS Code will add useful annotations to the gutter and to the overview ruler. +* Create, review, and merge pull requests +* View and manage issues +* Comment on and approve PRs without leaving VS Code +* Check out PR branches and review changes locally -* A red triangle indicates where lines have been deleted -* A green bar indicates new added lines -* A blue bar indicates modified lines +Learn more about [working with GitHub in VS Code](/docs/sourcecontrol/github.md). -![Gutter indicators](images/overview/gutter.png) +## Other source control providers -## Merge conflicts +VS Code supports multiple source control providers. While Git support is built-in, you can [install extensions](https://marketplace.visualstudio.com/search?target=VSCode&category=SCM%20Providers&sortBy=Installs) for other version control systems like Azure DevOps, Subversion, or Mercurial. -![Git merge](images/overview/merge-conflict.png) - -Merge conflicts are recognized by VS Code. Differences are highlighted and there are inline actions to accept either one or both changes. Once the conflicts are resolved, stage the conflicting file so you can commit those changes. - -## Resolve merge conflicts with AI (Experimental) - -If you have [AI features enabled in VS Code](/docs/copilot/setup.md), you can use AI to help you resolve Git merge conflicts. Select the **Resolve Conflicts with AI** button in the editor to open the Chat view and start an agentic flow to help you resolve the merge conflict. The merge base and changes from each branch are provided as context for the AI. - -![Screenshot of the proposed merge conflict resolution in the editor.](images/overview/ai-merge-conflict-resolution.png) - -You can review the proposed merge conflict resolution in the editor and follow up with additional context if needed. You can customize the merge conflict resolution by using an `AGENTS.md` file. - -## 3-way merge editor - -To help you resolve merge conflicts, VS Code provides a 3-way merge editor where you can interactively accept incoming and current changes and view and edit the resulting merged file. The 3-way merge editor is opened by selecting the **Resolve in Merge Editor** button in the bottom right corner of a file with Git merge conflicts. - -The 3-way merge editor displays separate views for **Incoming** changes (on the left), **Current** changes (on the right), and the **Result** of the merge (at the bottom). Conflicts are highlighted and can be resolved by using the CodeLens buttons. - -![3-way merge editor](images/overview/merge-editor-overview.png) - -### Resolving conflicts - -The 3-way merge editor allows you to resolve conflicts by accepting either one or both changes. You can also manually edit the result of the merge. - -For some conflicts, the merge editor shows an **Accept Combination** button. Accepting the combination resolves the current conflict by smartly merging both changes. This is especially useful for changes in the same line that don't touch the same characters. - -Use the **Ignore** buttons to accept neither the incoming nor current change, but mark the conflict as resolved. This resets the conflicting area to the state before any changes were made. - -### Completing the merge - -You can use the conflict counter in the right of the result editor to keep track of how many unresolved conflicts are remaining. Clicking on the counter jumps to the next unresolved conflict. Once all conflicts are resolved, you can complete the merge by selecting **Complete Merge** in the bottom right corner. This stages the file and closes the merge editor. - -### Alternative layouts and more - -Selecting the three dots (**···**) in the top right corner of the merge editor opens a context menu with additional options. You can switch to a vertical layout and display the base view, which shows the state of the file before any changes were made. - -The three dots next to **Incoming**, **Current**, and **Result** offer options for each view, such as showing a side-by-side diff against base, accepting all changes, or resetting the result. - -### Understanding conflicts - -If you want to learn more about the details of how 3-way merge editors work, we can recommend the following video: - - - -## Viewing diffs - -Our Git tooling supports viewing of diffs within VS Code. - -![A File Diff in VS Code](images/overview/diff.png) - -The Diff editor has a separate gutter in the middle, which enables you to **Stage** or **Revert** changes code blocks. If you select a block of text, you can revert or stage the changes that are included in the selection. - -![Screenshot of the Diff editor, showing the Stage and Revert controls in the gutter](images/overview/diffEditor-stage-revert-demo.gif) - -> [!TIP] -> You can diff any two files by first right-clicking on a file in the Explorer view and selecting **Select for Compare** and then right-click on the second file to compare with and select **Compare with Selected**. Alternatively, open the Command Palette (`kb(workbench.action.showCommands)`), and select any of the **File: Compare** commands. Learn more about the different options to [compare files in VS Code](/docs/editing/codebasics.md#compare-files). - -### Accessible Diff Viewer - -There is an Accessible Diff Viewer in the Diff editor that presents changes in a unified patch format. You can navigate between changes with **Go to Next Difference** (`kb(editor.action.accessibleDiffViewer.next)`) and **Go to Previous Difference** (`kb(editor.action.accessibleDiffViewer.prev)`). Lines can be navigated with arrow keys and pressing `kbstyle(Enter)` will jump back in the Diff editor and the selected line. - -![diff-review-pane](images/overview/diff-review-pane.png) - -> [!NOTE] -> This experience is especially helpful for screen reader users. - -## Timeline view - -The Timeline view, accessible at the bottom of the File Explorer by default, is a unified view for visualizing time-series events (for example, Git commits) for a file. - -![Timeline view](images/overview/timeline-view.png) - -VS Code's built-in Git support provides the Git commit history of the specified file. Selecting a commit will open a diff view of the changes introduced by that commit. When you right-click on a commit, you'll get options to **Copy Commit ID** and **Copy Commit Message**. - -Visual Studio Code supports more Git history workflows through [extensions](/docs/configure/extensions/extension-marketplace.md) available on the VS Code Marketplace. - -
- -> [!TIP] -> Click on an extension tile to read the description and reviews in the Marketplace. - -## Git output window - -You can always peek under the hood to see the Git commands we are using. This is helpful if something strange is happening or if you are just curious. :) - -To open the Git output window, run **View** > **Output** and select **Log (Git)** from the dropdown list. - -## VS Code as Git editor - -When you launch VS Code from the command line, you can pass the `--wait` argument to make the launch command wait until you have closed the new VS Code instance. This can be useful when you configure VS Code as your Git external editor so Git will wait until you close the launched VS Code instance. - -Here are the steps to do so: - -1. Make sure you can run `code --help` from the command line and you get help. - * if you do not see help, please follow these steps: - * macOS: Select **Shell Command: Install 'Code' command in path** from the **Command Palette**. - * Windows: Make sure you selected **Add to PATH** during the installation. - * Linux: Make sure you installed Code via our new `.deb` or `.rpm` packages. -2. From the command line, run `git config --global core.editor "code --wait"` - -Now you can run `git config --global -e` and use VS Code as editor for configuring Git. - -### VS Code as Git difftool and mergetool - -You can use VS Code's diff and merge capabilities even when using Git from command-line. Add the following to your Git configurations to use VS Code as the diff and merge tool: - -```ini -[diff] - tool = default-difftool -[difftool "default-difftool"] - cmd = code --wait --diff $LOCAL $REMOTE -[merge] - tool = code -[mergetool "code"] - cmd = code --wait --merge $REMOTE $LOCAL $BASE $MERGED -``` - -This uses the `--diff` option that can be passed to VS Code to compare two files side by side. The merge tool will be used the next time Git discovers a merge conflict. - -To summarize, here are some examples of where you can use VS Code as the editor: - -* `git rebase HEAD~3 -i` do interactive rebase using VS Code -* `git commit` use VS Code for the commit message -* `git add -p` followed by `kbstyle(e)` for interactive add -* `git difftool ^ ` use VS Code as the diff editor for changes - -## Working with GitHub Pull Requests and Issues - -Visual Studio Code can also bring in GitHub's pull requests and issues. Create your PRs in VS Code, review with comments, and approve them without switching context. Learn more about [GitHub PRs and Issues in VS Code](/docs/sourcecontrol/github.md). - -## SCM Providers +Browse available SCM provider extensions in the Extensions view (`kb(workbench.view.extensions)`) by searching for `@category:"scm providers"`.
-> [!TIP] -> Click on an extension tile to read the description and reviews in the Marketplace. - -VS Code has support for handling multiple Source Control providers simultaneously. For example, you can open multiple Git repositories alongside your Azure DevOps Server local workspace and seamlessly work across your projects. To turn on the **Source Control Providers** view, select the overflow menu in the **Source Control** view (`kb(workbench.view.scm)`), hover over **Views**, and make sure that **Source Control Repositories** is marked with a check. The **Source Control Providers** view shows the detected providers and repositories, and you can scope the display of your changes by selecting a specific provider. - -![Source Control Repositories view option in overflow menu](images/overview/scm-providers-list.png) - -### SCM Provider extensions - -If you would like to install another SCM provider, you can search on the **scm providers** extension category in the **Extensions** view (`kb(workbench.view.extensions)`). Start typing '@ca' and you will see suggestions for extension categories like debuggers and linters. Select `@category:"scm providers"` to see available SCM providers. - -![SCM Provider category in the marketplace](images/overview/scm-provider-category.png) - ## Next steps -* [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support. - -* [Intro to collaborating on GitHub](/docs/sourcecontrol/github.md) - Learn how to use GitHub with VS Code. - -* Learn more about [Copilot VS Code](/docs/copilot/overview.md) - Learn about Copilot in VS Code. - -* [Source Control API](/api/extension-guides/scm-provider.md) - If you want to integrate another Source Control provider into VS Code, see our Source Control API. +* [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in VS Code +* [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered features beyond Git workflows From 60ec99b9c36a8deafb84fa8feacddbce3e5e20dc Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Wed, 19 Nov 2025 13:59:59 +0100 Subject: [PATCH 02/12] Edit pass --- docs/sourcecontrol/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index c57024beac..afb2911437 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -11,13 +11,13 @@ The integrated source control interface provides access to Git functionality thr Changes you make in the VS Code interface are synced with your command-line Git operations, so you can use both the UI and terminal as needed. The source control interface works alongside the command line rather than replacing it. - + ## Prerequisites To use Git features in VS Code, you need: -* VS Code uses your machine's Git installation. [Install Git version 2.0.0.0 or later](https://git-scm.com/download) on your machine. +* VS Code uses your machine's Git installation. [Install Git version 2.0.0 or later](https://git-scm.com/download) on your machine. * When you commit changes, Git uses your configured username and email. You can set these values with: From 399b9fe13be553922a6241cb7d8928848c7f3d5c Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Wed, 19 Nov 2025 19:24:44 +0100 Subject: [PATCH 03/12] Add source control quickstart --- build/sitemap.xml | 5 + .../quickstart/ai-code-review-button.png | 3 + .../quickstart/clone-repository-url.png | 3 + .../images/quickstart/commit-button.png | 3 + .../images/quickstart/diff-editor.png | 3 + .../images/quickstart/git-modified-files.png | 3 + .../quickstart/initialize-repository.png | 3 + .../images/quickstart/pull-push-commands.png | 3 + .../quickstart/source-control-graph.png | 3 + .../quickstart/stage-changes-button.png | 3 + .../images/quickstart/sync-changes.png | 3 + docs/sourcecontrol/overview.md | 6 +- docs/sourcecontrol/quickstart.md | 149 ++++++++++++++++++ docs/toc.json | 3 +- 14 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 docs/sourcecontrol/images/quickstart/ai-code-review-button.png create mode 100644 docs/sourcecontrol/images/quickstart/clone-repository-url.png create mode 100644 docs/sourcecontrol/images/quickstart/commit-button.png create mode 100644 docs/sourcecontrol/images/quickstart/diff-editor.png create mode 100644 docs/sourcecontrol/images/quickstart/git-modified-files.png create mode 100644 docs/sourcecontrol/images/quickstart/initialize-repository.png create mode 100644 docs/sourcecontrol/images/quickstart/pull-push-commands.png create mode 100644 docs/sourcecontrol/images/quickstart/source-control-graph.png create mode 100644 docs/sourcecontrol/images/quickstart/stage-changes-button.png create mode 100644 docs/sourcecontrol/images/quickstart/sync-changes.png create mode 100644 docs/sourcecontrol/quickstart.md diff --git a/build/sitemap.xml b/build/sitemap.xml index 1abd6c7d76..ff5e3ca670 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -290,6 +290,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/quickstart + weekly + 0.8 + https://code.visualstudio.com/docs/sourcecontrol/intro-to-git weekly diff --git a/docs/sourcecontrol/images/quickstart/ai-code-review-button.png b/docs/sourcecontrol/images/quickstart/ai-code-review-button.png new file mode 100644 index 0000000000..65ea0e9f86 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/ai-code-review-button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:74b1b079034c9836f97649083781368284d0321520350208c7d88f8144ccec36 +size 32151 diff --git a/docs/sourcecontrol/images/quickstart/clone-repository-url.png b/docs/sourcecontrol/images/quickstart/clone-repository-url.png new file mode 100644 index 0000000000..09f72f34d9 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/clone-repository-url.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f0267cbdccd81e7f2caceed9c64535956575573c1a0859ff8178f6d6bfe50e84 +size 68741 diff --git a/docs/sourcecontrol/images/quickstart/commit-button.png b/docs/sourcecontrol/images/quickstart/commit-button.png new file mode 100644 index 0000000000..3887c85a41 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/commit-button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:92316006a8917f174804051cf5e7ab019a453b51723e809c8682e2411a5b576d +size 49121 diff --git a/docs/sourcecontrol/images/quickstart/diff-editor.png b/docs/sourcecontrol/images/quickstart/diff-editor.png new file mode 100644 index 0000000000..74243deac2 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/diff-editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:53522309f89a2fbdb40f5f100229fe090e516d0790bc75c699058e805d244816 +size 91409 diff --git a/docs/sourcecontrol/images/quickstart/git-modified-files.png b/docs/sourcecontrol/images/quickstart/git-modified-files.png new file mode 100644 index 0000000000..e19a37ab0e --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/git-modified-files.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:94ead9a23eacce804f587e323b891ded1cfef3f6de613868ac9aa19110362aa8 +size 45980 diff --git a/docs/sourcecontrol/images/quickstart/initialize-repository.png b/docs/sourcecontrol/images/quickstart/initialize-repository.png new file mode 100644 index 0000000000..9cc37bc689 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/initialize-repository.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:983af441722dccba3e9a5571a4d84a13ca2107f93ac2a87f51d88e9ea0a8f162 +size 81478 diff --git a/docs/sourcecontrol/images/quickstart/pull-push-commands.png b/docs/sourcecontrol/images/quickstart/pull-push-commands.png new file mode 100644 index 0000000000..e0df0ddca7 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/pull-push-commands.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:37a0b3a7d0eb7ce63053a5044c05375766bfa53170d910d09b81ef8de13a4560 +size 80215 diff --git a/docs/sourcecontrol/images/quickstart/source-control-graph.png b/docs/sourcecontrol/images/quickstart/source-control-graph.png new file mode 100644 index 0000000000..332c15794f --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/source-control-graph.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:08be19a2e190e3f85bff7895b7caa0548e573b284fb7d572735751ff66931cd8 +size 65679 diff --git a/docs/sourcecontrol/images/quickstart/stage-changes-button.png b/docs/sourcecontrol/images/quickstart/stage-changes-button.png new file mode 100644 index 0000000000..995f8a9b81 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/stage-changes-button.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4a3ace2049f0776bff691dadf84b825feee448888589cf487c9a2181722f9db8 +size 53373 diff --git a/docs/sourcecontrol/images/quickstart/sync-changes.png b/docs/sourcecontrol/images/quickstart/sync-changes.png new file mode 100644 index 0000000000..90e7d09b73 --- /dev/null +++ b/docs/sourcecontrol/images/quickstart/sync-changes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:230d30cac4efd4ce9ab74fcc75876848af7bae5f001d12b6c450dfc625e6dcb0 +size 50939 diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index afb2911437..9ff953229b 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -143,6 +143,10 @@ Browse available SCM provider extensions in the Extensions view (`kb(workbench.v ## Next steps +* [Source Control Quickstart](/docs/sourcecontrol/quickstart.md) - Quickly get started with Git source control in VS Code + * [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support -* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in VS Code + +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in +VS Code * [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered features beyond Git workflows diff --git a/docs/sourcecontrol/quickstart.md b/docs/sourcecontrol/quickstart.md new file mode 100644 index 0000000000..94bcbed6b7 --- /dev/null +++ b/docs/sourcecontrol/quickstart.md @@ -0,0 +1,149 @@ +--- +ContentId: 5f83254d-2817-4398-9321-456789abcdef +DateApproved: 11/19/2025 +MetaDescription: Quickly get started with Git source control in Visual Studio Code. Initialize a repository, stage changes, and commit code in minutes. +--- +# Quickstart: use source control in VS Code + +Get up and running with Git in Visual Studio Code in minutes. This guide covers the essentials of setting up a repository, saving your changes, and syncing your code. + +## Prerequisites + +1. **Install Git**: make sure Git is installed on your computer. [Download Git](https://git-scm.com/downloads) + +1. **Open VS Code**: make sure you have the latest version of [Visual Studio Code](https://code.visualstudio.com/download) installed. + +## Step 1: Open a project + +You can start with an existing Git repository or a local project folder. + +### Option A: Clone a repository locally + +Clone a repository if you want to work on code that is already hosted on GitHub, Azure DevOps, or another Git provider. If you have previously cloned the repository, you can open the folder directly in VS Code and VS Code will detect the Git repository automatically. + +To clone a repository in VS Code: + +1. Open the Source Control view (`kb(workbench.view.scm)`) and select **Clone Repository** + + ![Screenshot of the Source Control view with the Clone Repository button highlighted.](images/quickstart/clone-repository-url.png) + + Alternatively, open the Command Palette (`kb(workbench.action.showCommands)`) and enter `Git: Clone`. + +1. Enter the repository URL (for example, `https://github.com/microsoft/PowerToys`) + + If you're cloning from GitHub, you can also select **Clone from GitHub** and sign in to your GitHub account to see a list of your repositories. + +1. Select a parent folder on your computer to save the project + +1. Select **Open** when prompted to open the cloned repository in VS Code + +1. Confirm whether you trust the repository in the [Workspace Trust](/docs/editing/workspaces/workspace-trust.md) dialog + + > [!CAUTION] + > Only trust repositories from sources you know. Untrusted code can potentially harm your computer. + +### Option B: Initialize a repository in a local folder + +To start a new project with Git, you can initialize a repository in an existing local folder. This option creates a new Git repository in your folder to track changes. + +1. Open your project folder in VS Code (**File** > **Open Folder...**). + +1. Open the Source Control view (`kb(workbench.view.scm)`) and select **Initialize Repository** + + ![Screenshot of the Source Control view with the Initialize Repository button highlighted.](images/quickstart/initialize-repository.png) + + Alternatively, open the Command Palette (`kb(workbench.action.showCommands)`) and enter `Git: Initialize Repository`. + +## Step 2: Make changes and review + +Git tracks changes to files in your project. The Source Control view in VS Code is your hub for managing these changes without using the command line. + +Let's make a simple code change and use the Source Control view and diff editor to review it. + +1. Edit an existing file in your project, and save it. + + If you've just initialized a new repository, you can move on to the next step. + +1. Open the Source Control view (`kb(workbench.view.scm)`). + + Notice that the changed file(s) are listed under **Changes** with a "U" (untracked) or "M" (modified) icon next to them. The source control icon in the Activity Bar also shows a badge with the number of changed files. + + ![Screenshot of the Source Control view showing a modified and new file under Changes.](images/quickstart/git-modified-files.png) + +1. To review the changes to a file, select it in the Source Control view to open a diff editor. + + A diff editor shows the differences between the current version of the file and the last committed version. If the window is wide enough, the diff editor displays a side-by-side comparison, otherwise the changes are shown inline. + + ![Screenshot of the Diff Editor showing side-by-side changes between file versions.](images/quickstart/diff-editor.png) + + > [!TIP] + > If you have a Copilot subscription, select the Code Review button in the Source Control view to perform an AI-powered code review of your changes before committing them. + > + > ![Screenshot of the Code Review button in the Source Control view.](images/quickstart/ai-code-review-button.png) + +## Step 3: Stage and commit + +Git uses a two-step process to save changes: Stage (prepare) and Commit (save). In the Source Control view, changes are first listed under **Changes** and after staging them, they move to **Staged Changes** where they are ready to be committed. + +1. To stage your changes, do one of the following: + + * Hover over a file in the **Changes** list and select **+** (plus) to stage it + + ![Screenshot of the Source Control view with the Stage Changes button highlighted.](images/quickstart/stage-changes-button.png) + + * Right-click a file in the **Changes** list and select **Stage Changes** + + * Hover over the **Changes** header and select the **+** (plus) button to stage all changes at once + +1. (Optional) You can unstage changes or discard changes if needed: + + * To unstage a file, hover over it in the **Staged Changes** list and select the **-** (minus) button + + * To discard changes to a file, right-click it in the **Changes** list and select **Discard Changes** + +1. To commit your staged changes you can provide a commit message. + + 1. Enter a commit message in the text box at the top of the Source Control view. + + You can also use AI to generate a commit message based on your staged changes by selecting the sparkle icon in the commit message input box. + + 1. Select **Commit** to commit your changes to your Git history + + ![Screenshot of the Commit button in the Source Control view.](images/quickstart/commit-button.png) + + After committing, the staged changes are cleared from the Source Control view and saved in your local Git history. + + > [!NOTE] + > Only staged changes are included in a commit. If you have unstaged changes, they remain listed under **Changes** for future commits. + +1. To view your commit history, select the **Source Control Graph** in the Source Control view. + + ![Screenshot of the Source Control Graph in the Source Control view.](images/quickstart/source-control-graph.png) + +## Step 4: Sync with the server + +If your repository is connected to a remote server (for example, GitHub or Azure DevOps), you can sync your local commits with the remote repository. + +1. Open the Source Control view (`kb(workbench.view.scm)`) + +1. Select **Sync Changes** to pull the latest changes from the remote and push your local commits + + ![Screenshot of the Sync Changes button in the Source Control view.](images/quickstart/sync-changes.png) + + Alternatively, the Status Bar shows sync status and enables you to sync changes by selecting the sync icon (rotating arrows). + +1. Select it to pull new changes from the server and push your commits. + +1. To pull or push individually, select the ellipsis menu (...) in the Source Control view and choose **Pull** or **Push**. + + ![Screenshot of the Pull and Push commands in the Source Control view ellipsis menu.](images/quickstart/pull-push-commands.png) + +> [!TIP] +> If you started with a local folder (Option B) and want to save it to GitHub, use the **Publish to GitHub** button in the Source Control view. + +## Next steps + +Now that you know the basics, explore more features: + +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about Pull Requests and Issues. +* [Source Control Overview](/docs/sourcecontrol/overview.md) - Full reference for source control features. diff --git a/docs/toc.json b/docs/toc.json index cca368e675..cf1d6b6cb8 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -170,6 +170,7 @@ "area": "sourcecontrol", "topics": [ ["Overview", "/docs/sourcecontrol/overview"], + ["Quickstart", "/docs/sourcecontrol/quickstart"], ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], ["FAQ", "/docs/sourcecontrol/faq"] @@ -362,7 +363,7 @@ ["Azure Machine Learning", "/docs/datascience/azure-machine-learning"], ["Manage Jupyter Kernels", "/docs/datascience/jupyter-kernel-management"], ["Jupyter Notebooks on the Web", "/docs/datascience/notebooks-web"], - ["Data science in Microsoft Fabric", "/docs/datascience/microsoft-fabric-quickstart"] + ["Data science in Microsoft Fabric", "/docs/datascience/microsoft-fabric-quickstart"] ] }, { From 99e922b6ca1d1cb9b154d20f930a0296fa3f1c0c Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Fri, 21 Nov 2025 12:07:03 +0100 Subject: [PATCH 04/12] Add article about staging and commits --- build/sitemap.xml | 5 + .../copilot-code-review-results.png | 3 + .../staging-commits/copilot-code-review.png | 3 + .../staging-commits/diff-editor-inline.png | 3 + .../images/staging-commits/diff-editor.png | 3 + .../generate-commit-message.png | 3 + .../images/staging-commits/git-blame.mp4 | 3 + .../staging-commits/gutter-diff-preview.png | 3 + .../staging-commits/source-control-graph.png | 3 + .../images/staging-commits/stage-changes.png | 3 + .../staging-commits/stage-specific-lines.png | 3 + .../staging-commits/unstage-changes.png | 3 + .../images/staging-commits/view-changes.png | 3 + docs/sourcecontrol/overview.md | 6 +- docs/sourcecontrol/quickstart.md | 2 +- docs/sourcecontrol/staging-commits.md | 239 ++++++++++++++++++ docs/toc.json | 1 + 17 files changed, 287 insertions(+), 2 deletions(-) create mode 100644 docs/sourcecontrol/images/staging-commits/copilot-code-review-results.png create mode 100644 docs/sourcecontrol/images/staging-commits/copilot-code-review.png create mode 100644 docs/sourcecontrol/images/staging-commits/diff-editor-inline.png create mode 100644 docs/sourcecontrol/images/staging-commits/diff-editor.png create mode 100644 docs/sourcecontrol/images/staging-commits/generate-commit-message.png create mode 100644 docs/sourcecontrol/images/staging-commits/git-blame.mp4 create mode 100644 docs/sourcecontrol/images/staging-commits/gutter-diff-preview.png create mode 100644 docs/sourcecontrol/images/staging-commits/source-control-graph.png create mode 100644 docs/sourcecontrol/images/staging-commits/stage-changes.png create mode 100644 docs/sourcecontrol/images/staging-commits/stage-specific-lines.png create mode 100644 docs/sourcecontrol/images/staging-commits/unstage-changes.png create mode 100644 docs/sourcecontrol/images/staging-commits/view-changes.png create mode 100644 docs/sourcecontrol/staging-commits.md diff --git a/build/sitemap.xml b/build/sitemap.xml index ff5e3ca670..359f187f6b 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -300,6 +300,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/staging-commits + weekly + 0.8 + https://code.visualstudio.com/docs/sourcecontrol/github weekly diff --git a/docs/sourcecontrol/images/staging-commits/copilot-code-review-results.png b/docs/sourcecontrol/images/staging-commits/copilot-code-review-results.png new file mode 100644 index 0000000000..7e25198cb6 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/copilot-code-review-results.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1dd90f00850bb4f7f0755fd36ad4f77fb9b9424196f791cfc0310302a2ee552d +size 155103 diff --git a/docs/sourcecontrol/images/staging-commits/copilot-code-review.png b/docs/sourcecontrol/images/staging-commits/copilot-code-review.png new file mode 100644 index 0000000000..0a1f7bd32a --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/copilot-code-review.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4ca0c99e483698ed5a9b2879af7495e4f800bdcd8630440db7984173a36ed57b +size 54691 diff --git a/docs/sourcecontrol/images/staging-commits/diff-editor-inline.png b/docs/sourcecontrol/images/staging-commits/diff-editor-inline.png new file mode 100644 index 0000000000..f45c99a410 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/diff-editor-inline.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1dc92beb2d5c3d7f14c4b1973110574a0aea3039e30f24a9e3def10298bca513 +size 128255 diff --git a/docs/sourcecontrol/images/staging-commits/diff-editor.png b/docs/sourcecontrol/images/staging-commits/diff-editor.png new file mode 100644 index 0000000000..656bc9fe9c --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/diff-editor.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4db7e9a96aa10381930232100e848c7d18e525c7b13c3b681640318b09b39489 +size 329149 diff --git a/docs/sourcecontrol/images/staging-commits/generate-commit-message.png b/docs/sourcecontrol/images/staging-commits/generate-commit-message.png new file mode 100644 index 0000000000..8ba2f891e2 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/generate-commit-message.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:19d8e0227a77b2c9fe41758e6d2322483a77e77ba3dc26301b8aeb6d99da4beb +size 80366 diff --git a/docs/sourcecontrol/images/staging-commits/git-blame.mp4 b/docs/sourcecontrol/images/staging-commits/git-blame.mp4 new file mode 100644 index 0000000000..47a7c9f760 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/git-blame.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:406bc49049fc282aad488f8dfcc460ab9706a7648cda0d82fea23ebdb83ccf8a +size 222346 diff --git a/docs/sourcecontrol/images/staging-commits/gutter-diff-preview.png b/docs/sourcecontrol/images/staging-commits/gutter-diff-preview.png new file mode 100644 index 0000000000..e0b8379833 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/gutter-diff-preview.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e0a35807fef9c6b45c6e98f02a6dcafb478992b076758e1affb383c4e74fc892 +size 99305 diff --git a/docs/sourcecontrol/images/staging-commits/source-control-graph.png b/docs/sourcecontrol/images/staging-commits/source-control-graph.png new file mode 100644 index 0000000000..0c4d85a776 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/source-control-graph.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cd509d4705d06a50628c3276ff95404776bb7670a1f312a92062e5a121d7ce65 +size 105377 diff --git a/docs/sourcecontrol/images/staging-commits/stage-changes.png b/docs/sourcecontrol/images/staging-commits/stage-changes.png new file mode 100644 index 0000000000..00d27231fa --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/stage-changes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0c85835c59130059c60feebc8a671a5ce00c8ba624db3f2d2fe6cbf9b21b2f3d +size 73859 diff --git a/docs/sourcecontrol/images/staging-commits/stage-specific-lines.png b/docs/sourcecontrol/images/staging-commits/stage-specific-lines.png new file mode 100644 index 0000000000..3ec69e7644 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/stage-specific-lines.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:698a74fb463be4b944866ef5a28acb8aba927f312a152fb148da7138b1662f80 +size 239760 diff --git a/docs/sourcecontrol/images/staging-commits/unstage-changes.png b/docs/sourcecontrol/images/staging-commits/unstage-changes.png new file mode 100644 index 0000000000..cf60260da1 --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/unstage-changes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0c3fa94f75a7b22184596b3ab864460c18ff51a00c75263968dab0a519f16b77 +size 74521 diff --git a/docs/sourcecontrol/images/staging-commits/view-changes.png b/docs/sourcecontrol/images/staging-commits/view-changes.png new file mode 100644 index 0000000000..2b57a4891d --- /dev/null +++ b/docs/sourcecontrol/images/staging-commits/view-changes.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e0e9d562c841573fcd14cfb1e3bcca14cf82b5ed87e8c37ef0efcde407d346e9 +size 54904 diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index 9ff953229b..b0ba6aabbc 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -82,6 +82,8 @@ Type your commit message in the input box or select the sparkle icon ( [!TIP] +> You can view the list of changes in either a flat or tree structure. Toggle this with the **More Actions** (**...**) > **View & Sort** > **View as Tree/List** option in the Source Control view toolbar. + +### Editor gutter indicators + +To help you quickly identify changes in your files, VS Code shows gutter indicators in the editor next to the line number to represent added, modified, or deleted lines since your last commit. You can also see these indicators in the [minimap](/docs/getstarted/userinterface.md#minimap). + +The gutter color indicates the type of change: + +* **Green bar**: new lines added since the last commit +* **Blue bar**: lines modified since the last commit +* **Red triangle**: lines deleted (shown above the deletion point) + +When you select the gutter indicator, an inline diff preview of your changes appears. You can stage or revert changes directly from this preview using the corresponding buttons. + +![Screenshot of editor gutter indicators showing line changes and a hover showing Git blame information.](images/staging-commits/gutter-diff-preview.png) + +You can customize the gutter indicator behavior with these settings: + +* `setting(scm.diffDecorations)`: control when diff decorations appear (all, gutter, overview, minimap, or none) +* `setting(scm.diffDecorationsGutterAction)`: control the actions available in the gutter menu +* `setting(scm.diffDecorationsGutterPattern)`: customize the pattern used for gutter decorations +* `setting(scm.diffDecorationsGutterVisibility)`: control when to show gutter decorations (always or on hover) +* `setting(scm.diffDecorationsGutterWidth)`: set the width of the gutter indicator +* `setting(scm.diffDecorationsIgnoreTrimWhitespace)`: ignore whitespace changes in diff decorations + +## Staging changes + +Staging changes prepares them for adding to your next commit. You can stage entire files or specific lines and code blocks for more granular control. + +To stage individual files, hover over them in the **Changes** list and select the **+** (plus) icon, or right-click the file and select **Stage Changes**. You can also drag files from the **Changes** section and drop them into the **Staged Changes** section to stage them. + +![Screenshot of staging changes in the Source Control view.](images/staging-commits/stage-changes.png) + +When you're using the tree view, you can stage entire folders by staging the folder itself. To stage all modified files at once, hover over the **Changes** header and select the **+** (plus) icon. + +There are more specialized staging actions available in the Command Palette (`kb(workbench.action.showCommands)`). Type "Git: Stage" to see options for staging files. + +### Stage specific lines or code blocks + +Instead of staging entire files, you can also stage specific parts of a file. Partial staging enables you to create focused commits. For example, if you've made formatting changes and bug fixes in the same file, you can commit them separately with appropriate commit messages. + +You can perform partial staging from the diff editor: + +1. Select a file in the **Changes** list to open the [diff editor](#review-changes-with-the-diff-editor) + +1. Select the lines you want to stage + +1. Use the **Stage** button in the gutter of the diff editor next to your selection to stage only those lines + + ![Screenshot of staging specific lines from the diff editor.](images/staging-commits/stage-specific-lines.png) + + You can also right-click the selection and choose **Stage Selected Ranges** or run **Git: Stage Selected Ranges** from the Command Palette. + +### Unstage changes + +To remove files from staging, hover over them in the **Staged Changes** list and select the **-** (minus) icon, or right-click and choose **Unstage Changes**. The files move back to the **Changes** section without losing your modifications. + +![Screenshot of unstaging changes in the Source Control view.](images/staging-commits/unstage-changes.png) + +Similarly, you can also unstage specific lines or code blocks from the diff editor using the **Unstage** button in the gutter next to your selection. + +## Commit your changes + +Once you've staged your changes, you can create a commit to save them to your local repository. To create a commit, you need to write a commit message that describes the changes. This message helps you and others understand the purpose of the commit when reviewing the commit history. + +### Write commit messages + +A commit message describes the changes you're committing and helps others (and your future self) understand the purpose of the commit. Type your message in the commit message input box at the top of the Source Control view and select **Commit** to save your staged changes. + +To help you write a commit message, select the sparkle icon in the commit message input box to use AI to generate the message based on your staged changes. You can [create custom instructions](/docs/copilot/customization/custom-instructions.md#specify-custom-instructions-in-settings) to guide the AI in generating messages. + +![Screenshot of generating a commit message with AI.](images/staging-commits/generate-commit-message.png) + +If you want to write commit messages with multiple paragraphs, you can use a full editor instead of the input box. Enable this with the `setting(git.useEditorAsCommitInput)` setting. When you commit changes without a commit message, a new editor tab opens for you to write your message. + +> [!TIP] +> To cycle through your previous commit messages, press `kb(history.showPrevious)` and `kb(history.showNext)` while focused in the commit message input box. + +### Commit changes + +Select the **Commit** button in the Source Control view to commit the changes in the **Staged Changes** section. Any unstaged changes remain in the **Changes** section for future commits. + +To commit all changes (staged and unstaged) at once, select the **More Actions** (**...**) menu and choose **Commit** > **Commit All**. This stages and commits all modified files in one step. + +### Amend the previous commit + +If you need to modify your most recent commit, you can amend it instead of creating a new commit. This is useful for adding forgotten changes or correcting the commit message. + +To amend a commit, select the **Commit** button dropdown and select **Commit (Amend)**, or use the **Commit Staged (Amend)** option from the **More Actions** (**...**) menu. + +> [!NOTE] +> Only amend commits that haven't been pushed to a shared repository. Amending pushed commits rewrites history and can cause issues for other collaborators. + +### Undo the last commit + +If you need to undo your last commit, select the **More Actions** (**...**) menu in the Source Control view, then choose **Commit** > **Undo Last Commit**. This removes the last commit from your branch history but keeps all the changes from that commit staged in the **Staged Changes** section. + +### Discard changes + +To completely discard uncommitted changes and revert a file to its last committed state, right-click the file in the Source Control view and select **Discard Changes**. Alternatively, hover over the file in the **Changes** list and select the discard icon (a curved arrow pointing left). + +Discarded changes are moved to the Recycle Bin (Windows) or Trash (macOS/Linux), giving you a chance to recover them if needed. + +## Review changes with the diff editor + +The diff editor shows what changed in your files. It displays side-by-side comparisons of the original and modified versions. The diff editor can open in side-by-side or inline view. + +To open the diff editor, select any file in the Source Control view **Changes** or **Staged Changes** lists to see the changes for that file versus the last committed version. + +> [!TIP] +> For large files, collapse the unchanged sections by selecting the **Collapse Unchanged Regions** button in the diff editor toolbar. This helps you focus on the actual changes. You can also quickly navigate between changes using the **Next Change** and **Previous Change** buttons. + +### Side-by-side vs inline view + +By default, the diff editor shows a side-by-side comparison with the original file on the left and your changes on the right. + +![Screenshot of the Diff Editor showing side-by-side changes between file versions.](images/staging-commits/diff-editor.png) + +Toggle to inline view by selecting **More Actions** (**...**) > **Inline View** in the diff editor toolbar to view changes within one editor. + +![Screenshot of the Diff Editor showing inline changes between file versions.](images/staging-commits/diff-editor-inline.png) + +Configure your preferred default view with the `setting(diffEditor.renderSideBySide)` setting. + +### Stage and revert from the diff editor + +The diff editor includes a gutter with **Stage** and **Revert** buttons next to each change. These buttons let you: + +* Stage individual code blocks or lines directly from the diff view +* Revert specific changes without affecting other modifications + +If you select specific lines in the diff editor, the buttons operate only on your selection. + +You can hide the diff editor gutter with the `setting(diffEditor.renderGutterMenu)` setting. + +### Accessible diff viewer + +For screen reader users, VS Code provides the Accessible Diff Viewer, which presents changes in a unified patch format. To open the Accessible Diff Viewer, use the **More Actions** (**...**) menu in the diff editor toolbar and select **Open Accessible Diff Viewer** or use the `kb(editor.action.accessibleDiffViewer.next)` keyboard shortcut. + +Navigate through changes with **Go to Next Difference** (`kb(editor.action.accessibleDiffViewer.next)`) and **Go to Previous Difference** (`kb(editor.action.accessibleDiffViewer.previous)`) commands. + +## Review code changes with AI + +VS Code enables you to review your uncommitted changes using AI assistance before committing them. These AI features complement manual code review and help catch problems early in your development workflow. + +To perform an AI-powered code review of your uncommitted changes: + +1. Select the **Code Review** button in the Source Control view + + ![Screenshot of the Code Review button in the Source Control view.](images/staging-commits/copilot-code-review.png) + +1. VS Code analyzes your changes and generates review comments and suggestions, which appear as overlay comments in the editor + + ![Screenshot of the code review results, showing as editor overlay comments.](images/staging-commits/copilot-code-review-results.png) + +## Git blame information + +VS Code can show git blame information inline in the editor and in the Status Bar. Hover over the Status Bar item or editor inline hint to view detailed git blame information. + + + +To enable or disable git blame information, use the **Git: Toggle Git Blame Editor Decoration** and **Git: Toggle Git Blame Status Bar Item** commands, or configure these settings: + +* `setting(git.blame.statusBarItem.enabled)` (enabled by default) +* `setting(git.blame.editorDecoration.enabled)` + +You can customize the format of the message that is shown in the editor and in the Status Bar with the `setting(git.blame.editorDecoration.template)` and `setting(git.blame.statusBarItem.template)` settings. You can use variables for the most common information. + +For example, the following template shows the subject of the commit, the author's name, and the author's date relative to now: + +```json +{ + "git.blame.editorDecoration.template": "${subject}, ${authorName} (${authorDateAgo})" +} +``` + +To adjust the color of the editor decoration, use the `git.blame.editorDecorationForeground` theme color. + +## Graph view for commit history + +The Source Control Graph in the Source Control view provides a visual representation of your commit history and branch relationships. When you have a remote repository configured, you can see how many commits you are ahead or behind the remote. + +The graph contains the current branch, the current branch's upstream branch, and an optional base branch. The root of the graph is the common ancestor of these branches. + +![Screenshot showing the Source Control Graph.](images/staging-commits/source-control-graph.png) + +The graph provides the following functionality: + +* Select an entry to see the files that are changed in that commit. Select the **Open Changes** action to see the diff of the commit in the editor. +* Right-click on a commit to perform actions such as checkout, cherry-pick, adding it as context to chat, and more. +* Select a file to see the diff of that file in the editor. +* Select a commit and compare it with another branch or tag by right-clicking the commit and selecting **Compare with**, **Compare with Remote**, or **Compare with Merge Base**. + +Use the actions in the Graph view tool bar to select the branch, fetch, pull, push, and sync changes. + +## Timeline view for file history + +The Timeline view, accessible at the bottom of the File Explorer, is a unified view for visualizing the events history for a file. For example, you can view Git commits or local file saves in a timeline view. + +![Screenshot of the timeline view showing file commit history.](images/overview/timeline-view.png) + +Learn more about the [Timeline view](/docs/getstarted/userinterface.md#timeline-view). + +## Next steps + +* [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features like branching, merging, and remote operations +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues +* [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered development features diff --git a/docs/toc.json b/docs/toc.json index cf1d6b6cb8..09643059be 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -172,6 +172,7 @@ ["Overview", "/docs/sourcecontrol/overview"], ["Quickstart", "/docs/sourcecontrol/quickstart"], ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], + ["Staging and Committing", "/docs/sourcecontrol/staging-commits"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], ["FAQ", "/docs/sourcecontrol/faq"] ] From dd125cc406fdde5fbd37204a6413ef3ac9994151 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Fri, 21 Nov 2025 16:37:00 +0100 Subject: [PATCH 05/12] Add article about repos and remotes --- build/sitemap.xml | 5 + docs/sourcecontrol/github.md | 2 + .../repos-remotes/git-fetch-pull-push.png | 3 + .../repos-remotes/git-status-bar-sync.png | 3 + .../images/repos-remotes/github-clone.png | 3 + docs/sourcecontrol/overview.md | 8 +- docs/sourcecontrol/quickstart.md | 1 + docs/sourcecontrol/repos-remotes.md | 238 ++++++++++++++++++ docs/sourcecontrol/staging-commits.md | 5 +- docs/toc.json | 3 +- 10 files changed, 266 insertions(+), 5 deletions(-) create mode 100644 docs/sourcecontrol/images/repos-remotes/git-fetch-pull-push.png create mode 100644 docs/sourcecontrol/images/repos-remotes/git-status-bar-sync.png create mode 100644 docs/sourcecontrol/images/repos-remotes/github-clone.png create mode 100644 docs/sourcecontrol/repos-remotes.md diff --git a/build/sitemap.xml b/build/sitemap.xml index 359f187f6b..e05218f805 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -305,6 +305,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/repos-remotes + weekly + 0.8 + https://code.visualstudio.com/docs/sourcecontrol/github weekly diff --git a/docs/sourcecontrol/github.md b/docs/sourcecontrol/github.md index 7b6dc1b31c..87cec93bee 100644 --- a/docs/sourcecontrol/github.md +++ b/docs/sourcecontrol/github.md @@ -33,6 +33,8 @@ From the GitHub repository dropdown you can filter and pick the repository you w ![GitHub repository dropdown filtered on microsoft/vscode](images/github/github-repo-dropdown.png) +Learn more about [cloning repositories and working with remotes](/docs/sourcecontrol/repos-remotes.md#clone-repositories). + ### Authenticating with an existing repository Enabling authentication through GitHub happens when you run any Git action in VS Code that requires GitHub authentication, such as pushing to a repository that you're a member of or cloning a private repository. You don't need to have any special extensions installed for authentication; it is built into VS Code so that you can efficiently manage your repository. diff --git a/docs/sourcecontrol/images/repos-remotes/git-fetch-pull-push.png b/docs/sourcecontrol/images/repos-remotes/git-fetch-pull-push.png new file mode 100644 index 0000000000..aaf7655b2a --- /dev/null +++ b/docs/sourcecontrol/images/repos-remotes/git-fetch-pull-push.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:087fbd98ba26f0c6d400badd0457aac9adf20104fe99d4ea0e14154a40567966 +size 66401 diff --git a/docs/sourcecontrol/images/repos-remotes/git-status-bar-sync.png b/docs/sourcecontrol/images/repos-remotes/git-status-bar-sync.png new file mode 100644 index 0000000000..a523e7211b --- /dev/null +++ b/docs/sourcecontrol/images/repos-remotes/git-status-bar-sync.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7d6b99b5f58c3648f48fab2a79284bccaa84feb83f8653cc37e6a039224d40f4 +size 2188 diff --git a/docs/sourcecontrol/images/repos-remotes/github-clone.png b/docs/sourcecontrol/images/repos-remotes/github-clone.png new file mode 100644 index 0000000000..220b8e2195 --- /dev/null +++ b/docs/sourcecontrol/images/repos-remotes/github-clone.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:aafd21bf4deb28efdd65949aa45d579af3d569031eed908ce62ae56205f9898d +size 18442 diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index b0ba6aabbc..96ee8391a0 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -42,6 +42,8 @@ VS Code automatically detects when you open a folder that's a Git repository and > [!TIP] > You can publish a local repository directly to GitHub with the **Publish to GitHub** command, which creates a new repository and pushes your commits in one step. +Learn more about [cloning and publishing repositories](/docs/sourcecontrol/repos-remotes.md#clone-repositories). + ## Source control interface VS Code provides Git functionality through several key interface elements. This UI integration enables you to perform Git operations without knowing terminal commands: @@ -90,6 +92,8 @@ When your branch is connected to a remote branch, VS Code shows sync status in t ![Screenshot of the Source Control view showing the sync button indicating outgoing and incoming changes.](images/overview/incoming-outgoing-changes.png) +Learn more about [working with repositories and remotes](/docs/sourcecontrol/repos-remotes.md). + ### Resolve merge conflicts When you encounter merge conflicts, VS Code highlights the conflicting files in the Source Control view. Open a file with conflicts to see inline conflict markers. You have several options to resolve the conflicts: @@ -151,6 +155,6 @@ Browse available SCM provider extensions in the Extensions view (`kb(workbench.v * [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support -* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in -VS Code +* [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in VS Code * [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered features beyond Git workflows diff --git a/docs/sourcecontrol/quickstart.md b/docs/sourcecontrol/quickstart.md index 2d2030c998..a48b2a5dee 100644 --- a/docs/sourcecontrol/quickstart.md +++ b/docs/sourcecontrol/quickstart.md @@ -145,5 +145,6 @@ If your repository is connected to a remote server (for example, GitHub or Azure Now that you know the basics, explore more features: +* [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories. * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about Pull Requests and Issues. * [Source Control Overview](/docs/sourcecontrol/overview.md) - Full reference for source control features. diff --git a/docs/sourcecontrol/repos-remotes.md b/docs/sourcecontrol/repos-remotes.md new file mode 100644 index 0000000000..8019511c0d --- /dev/null +++ b/docs/sourcecontrol/repos-remotes.md @@ -0,0 +1,238 @@ +--- +ContentId: 8f34d9b6-3185-426a-b6d9-7e5ac7138a31 +DateApproved: 11/12/2025 +MetaDescription: Master working with Git repositories and remotes in VS Code. Learn about cloning, publishing, push/pull/sync operations, upstream tracking, auto-fetch, and managing multiple repositories. +--- +# Working with repositories and remotes + +Git repositories and remotes enable you to collaborate with others by syncing your work across different locations. VS Code provides integrated tools for working with remote repositories without needing command-line Git knowledge. + +This article covers working with Git repositories and remotes, including cloning, publishing, syncing changes, and managing multiple repositories in VS Code. + +## Understanding remotes + +A remote is a Git repository hosted on another server, such as GitHub, Azure DevOps, or GitLab. Remotes enable collaboration by providing a central location where team members can share their work. + +When you clone a repository, Git automatically creates a remote named `origin` that points to the original repository. You can work with multiple remotes if you need to interact with different servers or repositories. + +Working with remotes involves three main operations: + +* **Fetch**: downloads commits from the remote without changing your working files. This lets you see what others have done without merging their changes into your work. + +* **Pull**: downloads commits from the remote and merges them into your current branch. This is fetch plus merge in one operation. + +* **Push**: uploads your local commits to the remote so others can access your changes. + +![Diagram of Git fetch, pull, and push operations between local and remote repositories.](images/repos-remotes/git-fetch-pull-push.png) + + + +When you push, Git needs to know which remote to send your commits to. By default, Git uses the upstream branch configured for your current branch. If no upstream is set, VS Code prompts you to publish the branch and set the upstream. + +## Add a remote + +To add a new remote to your repository: + +1. In the Source Control view (`kb(workbench.view.scm)`), select **More Actions** (**...**) > **Remotes** > **Add Remote** + + Alternatively, run the **Git: Add Remote** command from the Command Palette (`kb(workbench.action.showCommands)`). + +1. Enter the remote URL + +1. Enter a name for the remote (for example, `upstream`) + +Your repository now has an additional remote that you can fetch from or push to. + +Use similar steps to remove a remote (**Git: Remove Remote**). + +## Clone repositories + +Cloning creates a local copy of a remote repository on your machine. The cloned repository includes all branches, commits, and history from the remote. By default, Git configures a remote named `origin` pointing to the URL you cloned from. + +To clone a repository, run the **Git: Clone** command in the Command Palette (`kb(workbench.action.showCommands)`), or select the **Clone Repository** button in the Source Control view. + +If you clone from GitHub, VS Code prompts you to authenticate with GitHub. Then, select a repository from the list to clone to your machine. The list contains both public and private repositories. For other Git providers, enter the repository URL. + +![Screenshot of the Clone Repository prompt in VS Code.](images/repos-remotes/github-clone.png) + +When cloning, VS Code asks you to select a local folder to store the repository. After cloning, you can choose to open the cloned repository in a new window. + +The [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension enhances the GitHub integration with pull request and issue management. Learn more about [working with GitHub in VS Code](/docs/sourcecontrol/github.md). + +## Publish to GitHub + +If you have a local repository that isn't connected to a remote, you can publish it directly to GitHub from VS Code. + +To publish a repository to GitHub: + +1. Open the Source Control view + +1. Select **Publish to GitHub** in the Source Control view + +1. Sign in to GitHub if prompted + +1. Choose whether to create a public or private repository + +1. Select which files to include in the initial commit + +VS Code creates a new repository on GitHub, adds it as a remote, and pushes your commits. + +> [!TIP] +> Publishing to GitHub is the fastest way to get your local work online. It creates the repository, configures the remote, and pushes your commits in one step. + +## Push, pull, and sync + +Pushing, pulling, and syncing are the core operations for keeping your local work in sync with remote repositories. + +### Push commits + +Pushing uploads your local commits to the remote repository. To push commits: + +1. Commit your changes locally + +1. Select **More Actions** (**...**) > **Push** in the Source Control view + + Alternatively, select the sync icon in the Status Bar to both pull and push in one operation. If you want to push to a specific remote, use the **Push to** option. + + You can also push your local commits by using the Push icon in the Source Control Graph view toolbar. + +1. If prompted, sign in to authenticate with the remote + +Your commits are uploaded to the remote branch. Other team members can now pull your changes. + +> [!NOTE] +> If your branch doesn't have an upstream configured, VS Code prompts you to publish the branch first. + +### Pull commits + +Pulling downloads commits from the remote repository and merges them into your local branch. To pull commits: + +1. Select **More Actions** (**...**) > **Pull** in the Source Control view + + Alternatively, select the sync icon in the Status Bar to both pull and push in one operation. If you want to pull from a specific remote, use the **Pull from** option. + + You can also pull remote commits by using the Pull icon in the Source Control Graph view toolbar. + +1. VS Code downloads and merges the remote commits + +If there are conflicts between your local changes and the remote commits, VS Code helps you resolve them through the [merge conflict resolution tools](/docs/sourcecontrol/overview.md#resolve-merge-conflicts). + +### Pull with rebase + +Instead of merging remote changes, you can rebase your local commits on top of the remote changes: + +1. Select **More Actions** (**...**) > **Pull (Rebase)** in the Source Control view + +1. VS Code applies the remote commits first, then replays your local commits on top + +Rebasing creates a linear history without merge commits. Learn more about [Git rebase](https://git-scm.com/docs/git-rebase). + +### Sync changes + +Syncing combines pull and push operations - it first pulls changes from the remote, then pushes your local commits. This is the recommended way to keep your work synchronized. + +To sync changes: + +* Select **Sync Changes** in the Source Control view +* Select the sync icon in the Status Bar + +![Screenshot of the Sync Changes button in the Source Control view.](images/quickstart/sync-changes.png) + +The Status Bar sync indicator shows how many commits you have to push (↑) and pull (↓). For example, `↑2 ↓1` means you have 2 commits to push and 1 commit to pull. + +> [!TIP] +> Configure the `setting(git.confirmSync)` setting to control whether VS Code asks for confirmation before syncing. + +### Fetch commits + +Fetching downloads commits from the remote repository without merging them into your local branch. This lets you review incoming changes before integrating them. + +To fetch commits: + +* Select **More Actions** (**...**) > **Fetch** in the Source Control view +* Select **Fetch From All Remotes** to fetch from all configured remotes +* Select **Fetch (Prune)** to fetch and remove deleted remote branches (to always prune, enable the `setting(git.pruneOnFetch)` setting) + +After fetching, you can review the incoming commits in the Source Control Graph before merging them with **Pull**. + +To automatically fetch commits in the background, enable the `setting(git.autofetch)` setting (disabled by default). To configure the fetch interval, use the `setting(git.autofetchPeriod)` setting (default 180 seconds). + +## Status Bar sync actions + +The Status Bar provides quick access to common repository and remote operations without opening the Source Control view. + +### Branch indicator + +The branch indicator in the lower-left corner shows: + +* **Current branch name**: select to switch branches +* **Sync status**: number of commits to push (↑) and pull (↓) +* **Publishing state**: shows **Publish Branch** for unpublished branches + +![Screenshot of the Status Bar showing the branch indicator with sync status.](images/repos-remotes/git-status-bar-sync.png) + +The sync icon (rotating arrows) in the Status Bar enables you to sync your changes with the remote (push and pull). + +You can customize Status Bar behavior with these settings: + +* `setting(git.showActionButton)`: control which action button to show (sync or commit) +* `setting(git.showPushSuccessNotification)`: show a notification after successful push +* `setting(git.showCommitInput)`: show commit input in the Source Control view + +## Source Control Graph + +The Source Control Graph provides a visual representation of your commit history, branch relationships, and sync status with remotes. This makes it easy to understand incoming and outgoing changes. + +![Screenshot of the Source Control Graph showing commit history and incoming/outgoing commits.](images/staging-commits/source-control-graph.png) + +The graph displays: + +* **Current branch**: highlighted with a special indicator +* **Upstream branch**: shows commits on the remote that you haven't pulled +* **Incoming commits** (↓): commits on the remote that you can pull +* **Outgoing commits** (↑): your local commits that can be pushed +* **Other branches**: local and remote branches in your repository + +You can fetch, push, and pull directly from the graph toolbar. The graph view also shows incoming and outgoing changes, making it easy to see when you need to sync. Select an item in the graph to view the individual files changed in that commit. + +Customize the Source Control Graph with these settings: + +* `setting(scm.graph.showIncomingChanges)`: show or hide incoming commits +* `setting(scm.graph.showOutgoingChanges)`: show or hide outgoing commits +* `setting(git.graph.pageSize)`: number of commits to load initially + +Learn more about [viewing commit history with the Source Control Graph](/docs/sourcecontrol/staging-commits.md#graph-view-for-commit-history). + +## Working with multiple repositories + +The Repositories view enables you to manage multiple Git repositories in a single workspace. This is useful when working with projects that span multiple repositories. + +To show the Repositories view, run the **Source Control: Focus on Repositories View** command from the Command Palette (`kb(workbench.action.showCommands)`). Configure the `setting(scm.alwaysShowRepositories)` setting to always show the Repositories view in the Source Control view. + +VS Code automatically detects Git repositories when you open folders that contain them. If you open a folder with multiple repositories (like a monorepo), all repositories appear in the Repositories view. + +You can configure whether you want to have multiple repositories active in the Source Control view or a single repository at a time by changing the `setting(scm.repositories.selectionMode)` setting. + +## Credential helpers + +Credential helpers securely store your authentication credentials so you don't have to enter them every time you push or pull. You should [set up a credential helper](https://docs.github.com/get-started/getting-started-with-git/caching-your-github-credentials-in-git) to avoid getting asked for credentials every time VS Code interacts with a remote repository. + +## Next steps + +* [Source Control Overview](/docs/sourcecontrol/overview.md) - Learn about other Git features in VS Code +* [Staging and Committing](/docs/sourcecontrol/staging-commits.md) - Master the commit workflow +* [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about pull requests and GitHub integration +* [Introduction to Git](/docs/sourcecontrol/intro-to-git.md) - Understand Git concepts and terminology diff --git a/docs/sourcecontrol/staging-commits.md b/docs/sourcecontrol/staging-commits.md index 3ceb78f7a3..08688a3e3a 100644 --- a/docs/sourcecontrol/staging-commits.md +++ b/docs/sourcecontrol/staging-commits.md @@ -1,5 +1,5 @@ --- -ContentId: 903e7275-6ecc-4113-96e8-17bdc2451258 +ContentId: 344271ac-56df-4cea-b0a9-2c135f7f3dec DateApproved: 11/12/2025 MetaDescription: Master Git staging and commits in VS Code with granular file control, AI-powered commit messages, visual diff reviews, and comprehensive change tracking tools. --- @@ -234,6 +234,7 @@ Learn more about the [Timeline view](/docs/getstarted/userinterface.md#timeline- ## Next steps -* [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features like branching, merging, and remote operations +* [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories +* [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features like branching and merging * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues * [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered development features diff --git a/docs/toc.json b/docs/toc.json index 09643059be..a4adc92f8e 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -172,7 +172,8 @@ ["Overview", "/docs/sourcecontrol/overview"], ["Quickstart", "/docs/sourcecontrol/quickstart"], ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], - ["Staging and Committing", "/docs/sourcecontrol/staging-commits"], + ["Staging & Committing", "/docs/sourcecontrol/staging-commits"], + ["Repositories & Remotes", "/docs/sourcecontrol/repos-remotes"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], ["FAQ", "/docs/sourcecontrol/faq"] ] From d0b338a5244397beaab38a52bf07e385762e669f Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Mon, 24 Nov 2025 16:06:09 +0100 Subject: [PATCH 06/12] Add merge conflicts article --- build/sitemap.xml | 5 + docs/sourcecontrol/merge-conflicts.md | 166 ++++++++++++++++++++++++++ docs/sourcecontrol/overview.md | 2 + docs/sourcecontrol/quickstart.md | 1 + docs/sourcecontrol/repos-remotes.md | 2 +- docs/toc.json | 1 + 6 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 docs/sourcecontrol/merge-conflicts.md diff --git a/build/sitemap.xml b/build/sitemap.xml index e05218f805..502268438b 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -310,6 +310,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/merge-conflicts + weekly + 0.8 + https://code.visualstudio.com/docs/sourcecontrol/github weekly diff --git a/docs/sourcecontrol/merge-conflicts.md b/docs/sourcecontrol/merge-conflicts.md new file mode 100644 index 0000000000..6668380075 --- /dev/null +++ b/docs/sourcecontrol/merge-conflicts.md @@ -0,0 +1,166 @@ +--- +ContentId: 8f4e9d2a-3b5c-4e7a-9f1d-2c8a5b6e3d9f +DateApproved: 11/24/2025 +MetaDescription: Learn how to resolve Git merge conflicts in VS Code using inline editor actions, the 3-way merge editor, and AI-assisted resolution. +--- +# Resolve merge conflicts in VS Code + +Merge conflicts occur when Git cannot automatically combine changes from different branches. VS Code provides several tools to help you identify and resolve these conflicts efficiently. + +Learn how to resolve merge conflicts in Visual Studio Code using inline editor actions, the 3-way merge editor, and AI-assisted resolution. + +## Understanding merge conflicts + +A merge conflict happens when Git encounters competing changes that it cannot automatically resolve. Common scenarios include: + +* Two branches modify the same lines in a file +* One branch deletes a file that another branch modifies +* Two branches add different content at the same location + +When you attempt to merge, rebase, pull, or cherry-pick commits that contain conflicting changes, Git pauses the operation and marks the conflicts for you to resolve manually. + +## Recognize conflicts in VS Code + +When merge conflicts occur, VS Code provides multiple visual indicators to help you identify and resolve them. Files with conflicts appear in the Source Control view under a **Merge Changes** section. + +### Editor conflict markers + +When you open a file with conflicts, VS Code highlights the conflicting sections with the following markers: + +* `<<<<<<< HEAD` (or current branch name): marks the start of your current branch's changes +* `=======`: separates the two conflicting versions +* `>>>>>>> branch-name`: marks the end of the incoming branch's changes + +![Screenshot of inline conflict markers in the editor showing current and incoming changes.](images/overview/merge-conflict.png) + +### CodeLens actions + +Above each conflict, VS Code displays CodeLens actions that let you quickly resolve the conflict: + +* **Accept Current Change**: keep only your branch's version +* **Accept Incoming Change**: keep only the incoming branch's version +* **Accept Both Changes**: keep both versions, one after the other +* **Compare Changes**: open a diff view to see the differences side-by-side + +## Resolve conflicts with inline actions + +For simple conflicts, you can resolve them directly in the editor using the CodeLens actions: + +1. Open a file with conflicts from the Source Control view + +1. Review the conflicting sections marked with conflict markers + +1. Select one of the CodeLens actions above the conflict: + * **Accept Current Change** to keep your version + * **Accept Incoming Change** to keep the incoming version + * **Accept Both Changes** to keep both versions + +1. Repeat for each conflict in the file + +1. Save the file when all conflicts are resolved + +After resolving conflicts in a file, the conflict markers disappear and you can stage the file which moves to the **Staged Changes** section in the Source Control view. You can then proceed to commit the changes. + +> [!TIP] +> For more complex conflicts where you need to combine parts of both changes, you can manually edit the file. Delete the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) and edit the content to create the desired result. + +## Use the 3-way merge editor + +For more complex conflicts or when you want a side-by-side view of all changes, use the 3-way merge editor. This editor provides a comprehensive view with three panels: + +* **Incoming** (left): changes from the branch being merged +* **Current** (right): changes from your current branch +* **Result** (bottom): the merged result that will be saved + +### Open the merge editor + +To open the 3-way merge editor: + +1. Select a file with conflicts in the Source Control view + +1. Select **Open in Merge Editor** from the context menu, or select the **Resolve in Merge Editor** button that appears at the top of the editor + + ![Screenshot of the 3-way merge editor showing incoming, current, and result panels.](images/overview/merge-editor-overview.png) + +### Accept changes in the merge editor + +The merge editor displays conflicts with checkboxes next to each conflicting change. Use these checkboxes to choose which changes to accept: + +1. Review the changes in the **Incoming** and **Current** panels + +1. Use the editor CodeLens actions to select which changes to accept: + + * Accept either the **Incoming** or **Current** change + * Accept a **Combination of both** changes to smartly merge both changes + * **Ignore** the change to leave it out of the result + +1. The **Result** panel at the bottom updates automatically to show your selections + +1. Use the conflict count indicator in the right of the result editor to keep track of how many unresolved conflicts are remaining. + +1. When all conflicts are resolved, select **Complete Merge** to stage the changes and close the merge editor + +### Manual edits in the merge editor + +Sometimes you need to combine parts of both changes or create a completely new resolution. You can edit the **Result** panel directly: + +1. Select anywhere in the **Result** panel to place your cursor + +1. Edit the content as needed, combining elements from both changes or writing new code + +> [!TIP] +> Use the **Ignore** buttons in the **Incoming** or **Current** panels to hide changes you don't want to accept. This helps focus on the relevant conflicts. + +### Alternative layouts + +Selecting the three dots (···) in the top right corner of the merge editor opens a context menu with additional options. You can switch to a vertical layout and display the base view, which shows the state of the file before any changes were made. + +The three dots next to **Incoming**, **Current**, and **Result** offer options for each view, such as showing a side-by-side diff against base, accepting all changes, or resetting the result. + +## Resolve conflicts with AI (experimental) + +> [!NOTE] +> AI-assisted conflict resolution is an experimental feature and requires a GitHub Copilot subscription. + +VS Code can [use AI](/docs/copilot/setup.md) to help resolve merge conflicts automatically. This feature analyzes both versions of the conflicting changes and proposes a resolution: + +1. Open a file with conflicts in the editor + +1. Select the **Resolve Merge Conflict with AI** button at the top of the editor + + ![Screenshot of the AI merge conflict resolution button in the editor.](images/overview/ai-merge-conflict-resolution.png) + +1. VS Code opens the Chat view and starts an agentic flow to analyze the conflict + +1. Review the proposed changes in the editor + +1. Accept the resolution or make manual adjustments as needed + +The AI considers the merge base (the common ancestor of both branches) and the changes from each branch to generate a resolution that attempts to preserve the intent of both changes. + +## Complete the merge operation + +After resolving all conflicts, you need to complete the merge operation by committing the changes: + +1. Verify that all conflicting files have been resolved and are in the **Staged Changes** section + +1. Enter a commit message and select **Commit** to complete the merge + +> [!TIP] +> If you need to abandon a merge operation, select **Git: Abort Merge** from the Command Palette. This returns your repository to its state before the merge began. + +## Configure VS Code as default merge tool + +You can set VS Code as your default Git merge tool by running the following commands in your terminal. When you perform a merge in the command-line that results in conflicts, Git will open VS Code's merge editor to help you resolve them. + +```bash +git config --global merge.tool vscode +git config --global mergetool.vscode.cmd 'code --wait $MERGED' +``` + +## Next steps + +* [Staging and Committing](/docs/sourcecontrol/staging-commits.md) - Learn about staging changes and creating commits +* [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about working with remote repositories +* [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features in VS Code +* [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered development features diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index 96ee8391a0..73b6356117 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -106,6 +106,8 @@ When you encounter merge conflicts, VS Code highlights the conflicting files in Once resolved, you can stage the files and commit the merge. +Learn more about [resolving merge conflicts](/docs/sourcecontrol/merge-conflicts.md). + ### Work with branches, worktrees, and stashes VS Code supports multiple workflows for managing parallel development work. You can easily switch between branches within a single workspace. diff --git a/docs/sourcecontrol/quickstart.md b/docs/sourcecontrol/quickstart.md index a48b2a5dee..dfd97878ba 100644 --- a/docs/sourcecontrol/quickstart.md +++ b/docs/sourcecontrol/quickstart.md @@ -146,5 +146,6 @@ If your repository is connected to a remote server (for example, GitHub or Azure Now that you know the basics, explore more features: * [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories. +* [Resolve Merge Conflicts](/docs/sourcecontrol/merge-conflicts.md) - Learn how to handle conflicts when merging branches. * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about Pull Requests and Issues. * [Source Control Overview](/docs/sourcecontrol/overview.md) - Full reference for source control features. diff --git a/docs/sourcecontrol/repos-remotes.md b/docs/sourcecontrol/repos-remotes.md index 8019511c0d..cac2cde7d2 100644 --- a/docs/sourcecontrol/repos-remotes.md +++ b/docs/sourcecontrol/repos-remotes.md @@ -128,7 +128,7 @@ Pulling downloads commits from the remote repository and merges them into your l 1. VS Code downloads and merges the remote commits -If there are conflicts between your local changes and the remote commits, VS Code helps you resolve them through the [merge conflict resolution tools](/docs/sourcecontrol/overview.md#resolve-merge-conflicts). +If there are conflicts between your local changes and the remote commits, VS Code helps you resolve them through the [merge conflict resolution tools](/docs/sourcecontrol/merge-conflicts.md). ### Pull with rebase diff --git a/docs/toc.json b/docs/toc.json index a4adc92f8e..aa716bea0e 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -174,6 +174,7 @@ ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], ["Staging & Committing", "/docs/sourcecontrol/staging-commits"], ["Repositories & Remotes", "/docs/sourcecontrol/repos-remotes"], + ["Merge Conflicts", "/docs/sourcecontrol/merge-conflicts"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], ["FAQ", "/docs/sourcecontrol/faq"] ] From a58240339cea065f3ce73a71a633d5ad0a3e52a8 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Mon, 24 Nov 2025 16:59:21 +0100 Subject: [PATCH 07/12] Add article about branching and worktrees --- build/sitemap.xml | 4 +- docs/sourcecontrol/branches-worktrees.md | 162 +++++++++++++++ docs/sourcecontrol/github.md | 3 + .../branches-worktrees/current-branch.png | 3 + .../branches-worktrees/scm-create-branch.png | 3 + .../source-control-view-repositories.png | 0 .../worktree-compare-changes.png | 0 .../worktree-create.png | 0 docs/sourcecontrol/intro-to-git.md | 193 ------------------ docs/sourcecontrol/merge-conflicts.md | 6 +- docs/sourcecontrol/overview.md | 3 + docs/sourcecontrol/quickstart.md | 3 +- docs/sourcecontrol/repos-remotes.md | 4 +- docs/sourcecontrol/staging-commits.md | 3 +- docs/toc.json | 2 +- 15 files changed, 188 insertions(+), 201 deletions(-) create mode 100644 docs/sourcecontrol/branches-worktrees.md create mode 100644 docs/sourcecontrol/images/branches-worktrees/current-branch.png create mode 100644 docs/sourcecontrol/images/branches-worktrees/scm-create-branch.png rename docs/sourcecontrol/images/{overview => branches-worktrees}/source-control-view-repositories.png (100%) rename docs/sourcecontrol/images/{overview => branches-worktrees}/worktree-compare-changes.png (100%) rename docs/sourcecontrol/images/{overview => branches-worktrees}/worktree-create.png (100%) delete mode 100644 docs/sourcecontrol/intro-to-git.md diff --git a/build/sitemap.xml b/build/sitemap.xml index 502268438b..4b4932811c 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -296,12 +296,12 @@ 0.8 - https://code.visualstudio.com/docs/sourcecontrol/intro-to-git + https://code.visualstudio.com/docs/sourcecontrol/staging-commits weekly 0.8 - https://code.visualstudio.com/docs/sourcecontrol/staging-commits + https://code.visualstudio.com/docs/sourcecontrol/branches-worktrees weekly 0.8 diff --git a/docs/sourcecontrol/branches-worktrees.md b/docs/sourcecontrol/branches-worktrees.md new file mode 100644 index 0000000000..7346849434 --- /dev/null +++ b/docs/sourcecontrol/branches-worktrees.md @@ -0,0 +1,162 @@ +--- +ContentId: a9b2c3d4-e5f6-7890-ab12-cd3456789012 +DateApproved: 11/12/2025 +MetaDescription: Learn how to work with Git branches and worktrees in VS Code. Create, switch between, and manage multiple branches, use Git worktrees for parallel development, and manage stashes for temporary changes. +--- +# Git Branches and Worktrees in VS Code + +Git branches enable you to work on different features or experiments simultaneously without affecting your main codebase. VS Code provides tools for branch management, Git worktrees for parallel development, and stash management for temporary changes. + +This article covers working with branches, worktrees, and stashes in VS Code to manage parallel development work. + +## Working with branches + +Branches are lightweight, movable pointers to specific commits in your Git history. They allow you to diverge from the main line of development and work on features independently. + +For example, suppose you're working on a web application and need to add user authentication while also fixing a bug in the payment system. You can create two branches: + +* `feature/user-authentication` - contains your login and signup functionality +* `bugfix/payment-validation` - contains fixes for payment processing errors + +Each branch maintains its own set of changes without affecting the other. You can switch between branches to work on different tasks, and later merge the completed branches back into your main branch. + +### View current branch + +The current branch appears in several places in VS Code: + +* **Status Bar**: shows the current branch name and allows quick branch switching +* **Repositories view**: displays the current branch in the repository header +* **Source Control Graph**: visually represents branch relationships and history + +![Screenshot showing the current branch displayed in the Status Bar and Source Control view.](images/branches-worktrees/current-branch.png) + +### 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: + +1. Select the branch name in the Status Bar, or run the **Git: Checkout to** command from the Command Palette (`kb(workbench.action.showCommands)`). + +2. 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](#stash-management) before switching. + +### Create new branches + +Create a new branch to start working on a feature or experiment: + +1. Select the branch name in the Status Bar or run **Git: Create Branch** from the Command Palette. + +1. Enter a name for your new branch. Use descriptive names like `feature/user-authentication` or `bugfix/login-error`. + + > [!TIP] + > VS Code can generate random branch names for you. Configure this with the `setting(git.branchRandomName.enable)` and `setting(git.branchRandomName.dictionary)` settings. + +1. Choose the source branch (usually `main` or `develop`) from which to create the new branch. + +![Screenshot showing the create branch dialog with branch name input and source branch selection.](images/branches-worktrees/scm-create-branch.png) + +VS Code switches to the new branch after creation. + +> [!TIP] +> If you use the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) 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: + +1. Run **Git: Rename Branch** from the Command Palette or select it from the **More Actions** (...) menu. +1. Enter the new branch name. + +To delete a branch: + +1. Switch to a different branch (you can't delete the currently active branch). +1. Run **Git: Delete Branch** from the Command Palette or select it from the **More Actions** (...) menu. +1. 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: + +1. Switch to the target branch (usually `main` or `develop`). +1. Run **Git: Merge Branch** from the Command Palette. +1. 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](/docs/sourcecontrol/merge-conflicts.md). + +## Working with Git worktrees + +VS Code has built-in support for [Git worktrees](https://git-scm.com/docs/git-worktree), making it easy to manage and work with multiple branches at the same time. + +### Understanding worktrees + +A worktree is a separate checkout of a Git branch in its own directory. This allows you to have multiple working directories for the same repository, each on a different branch. Worktree functionality is especially useful for: + +* Work on multiple features simultaneously in separate folders +* Run different versions of your application side by side +* Compare implementations across branches + +### Create a worktree + +To create a new worktree in VS Code: + +1. Open the **Source Control Repositories** view from the Source Control view. + + ![Screenshot showing the Source Control Repositories view with multiple repositories listed.](images/branches-worktrees/source-control-view-repositories.png) + +1. Right-click on your repository and select **Worktree** > **Create Worktree**. + + ![Screenshot showing the worktree context menu in the Source Control Repositories view.](images/branches-worktrees/worktree-create.png) + +1. Follow the prompts to choose a branch and location for the new worktree. + + VS Code creates a new folder for the worktree at the specified location and checks out the selected branch into that folder. + +The new worktree appears as a separate entry in the **Source Control Repositories** view. + +### Switch between worktrees + +VS Code can display multiple repositories (including worktrees) simultaneously: + +* Each worktree appears as a separate repository in the **Source Control Repositories** view +* You can open multiple VS Code windows, each pointing to a different worktree +* Use **File** > **Open Recent** to quickly switch between worktree directories + +### Open a worktree + +There are multiple ways to open a worktree: + +* Directly open the folder associated with the worktree in VS Code. VS Code automatically detects that it's a worktree of an existing repository. + +* Right-click the worktree in the Source Control Repositories view and select **Open Worktree in New Window** or **Open Worktree in Current Window**. + +* Run the **Git: Open Worktree in Current Window** or **Git: Open Worktree in New Window** command in the Command Palette and select the desired worktree. + +### Compare and migrate changes from a worktree + +When you make changes in a worktree, you can compare those changes with your main workspace and bring worktree changes back into your main repository. + +1. In the Source Control view, right-click a changed file in the worktree and select **Compare with Workspace** to see the differences side-by-side. + + ![Screenshot showing the compare with workspace option in the worktree context menu and side-by-side diff view.](images/branches-worktrees/worktree-compare-changes.png) + +1. After reviewing, use the **Migrate Worktree Changes** command from the Command Palette to merge all changes from a worktree into your current workspace. + +## Next steps + +* [Staging and Committing](/docs/sourcecontrol/staging-commits.md) - Learn about committing changes within branches +* [Merge Conflicts](/docs/sourcecontrol/merge-conflicts.md) - Handle conflicts when merging branches +* [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Work with remote branches and collaboration +* [Collaborate on GitHub](/docs/sourcecontrol/github.md) - Use GitHub pull requests with your branch workflow \ No newline at end of file diff --git a/docs/sourcecontrol/github.md b/docs/sourcecontrol/github.md index 87cec93bee..6b671a277c 100644 --- a/docs/sourcecontrol/github.md +++ b/docs/sourcecontrol/github.md @@ -173,6 +173,9 @@ The Status bar also shows the active issue and if you select that item, a list o You can configure the name of the branch using the **GitHub Issues: Issue Branch Title** (`setting(githubIssues.issueBranchTitle)`) setting. If your workflow doesn't involve creating a branch, or if you want to be prompted to enter a branch name every time, you can skip that step by turning off the **GitHub Issues: Use Branch For Issues** (`setting(githubIssues.useBranchForIssues)`) setting. +> [!TIP] +> Learn more about [working with branches](/docs/sourcecontrol/branches-worktrees.md) to understand branch management, switching between branches, and organizing your development work. + Once you are done working on the issue and want to commit a change, the commit message input box in the **Source Control** view will be populated with a message, which can be configured with **GitHub Issues: Working Issue Format SCM** (`setting(githubIssues.workingIssueFormatScm)`). ## GitHub Repositories extension diff --git a/docs/sourcecontrol/images/branches-worktrees/current-branch.png b/docs/sourcecontrol/images/branches-worktrees/current-branch.png new file mode 100644 index 0000000000..b88900c649 --- /dev/null +++ b/docs/sourcecontrol/images/branches-worktrees/current-branch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b51b17870fb969507c2f6e1c6b049e860444afc1b950531e7a6bd1ef17430ea3 +size 186123 diff --git a/docs/sourcecontrol/images/branches-worktrees/scm-create-branch.png b/docs/sourcecontrol/images/branches-worktrees/scm-create-branch.png new file mode 100644 index 0000000000..88dc551751 --- /dev/null +++ b/docs/sourcecontrol/images/branches-worktrees/scm-create-branch.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ab38923377142d6360f5837c3dd52bd1a67caf6c9b807a96dee33e383a9102ae +size 102816 diff --git a/docs/sourcecontrol/images/overview/source-control-view-repositories.png b/docs/sourcecontrol/images/branches-worktrees/source-control-view-repositories.png similarity index 100% rename from docs/sourcecontrol/images/overview/source-control-view-repositories.png rename to docs/sourcecontrol/images/branches-worktrees/source-control-view-repositories.png diff --git a/docs/sourcecontrol/images/overview/worktree-compare-changes.png b/docs/sourcecontrol/images/branches-worktrees/worktree-compare-changes.png similarity index 100% rename from docs/sourcecontrol/images/overview/worktree-compare-changes.png rename to docs/sourcecontrol/images/branches-worktrees/worktree-compare-changes.png diff --git a/docs/sourcecontrol/images/overview/worktree-create.png b/docs/sourcecontrol/images/branches-worktrees/worktree-create.png similarity index 100% rename from docs/sourcecontrol/images/overview/worktree-create.png rename to docs/sourcecontrol/images/branches-worktrees/worktree-create.png diff --git a/docs/sourcecontrol/intro-to-git.md b/docs/sourcecontrol/intro-to-git.md deleted file mode 100644 index 845729d893..0000000000 --- a/docs/sourcecontrol/intro-to-git.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -ContentId: b3e4717d-81e2-4bfa-a022-c37aab950bce -DateApproved: 11/12/2025 -MetaDescription: Get started with Git in Visual Studio Code and take control of your code! Our beginner's guide covers everything you need to know, from setting up a repository to committing changes and collaborating with others. Learn Git today and streamline your development workflow. ---- -# Introduction to Git in VS Code - -Want to easily manage your source code and collaborate with others? Git and GitHub are the tools you need! And with Visual Studio Code, you can set up and use them in a snap. Even if you're a beginner, VS Code's user-friendly interface guides you through common Git actions like pushing and pulling code, creating and merging branches, and committing code changes. And if you're a pro, you'll love the ability to perform Git actions directly within the editor, saving you time and effort compared to using the Git command line. Plus, the seamless workflow between VS Code and Git means you can stay in your editor and get more done. - -With GitHub Copilot in VS Code, you can get suggestions for commit messages, pull requests, and review code changes before committing them. Learn more about [GitHub Copilot in VS Code](/docs/copilot/overview.md). - -> [!TIP] -> If you don't have a Copilot subscription yet, use Copilot for free by signing up for the [Copilot Free plan](https://github.com/github-copilot/signup). You'll get a monthly limit of completions and chat interactions. - -## Set up Git in VS Code - -To use Git and GitHub in VS Code, first make sure you [have Git installed on your computer](https://git-scm.com/downloads). If Git is missing, the **Source Control** view shows instructions on how to install it. Make sure to restart VS Code afterwards. - -Additionally you can sign into VS Code with your GitHub account in the **Accounts** menu in the lower right of the Activity bar to enable additional features like [Settings Sync](/docs/configure/settings-sync.md), but also cloning and publishing repositories from GitHub. - -![Screenshot of the Accounts menu in VS Code](images/intro/vscode-accounts-menu.png) - -## Open a Git repository - -VS Code provides several ways to get started in a Git repository, from local to remote cloud-powered environments like [GitHub Codespaces](https://github.com/features/codespaces). - -### Clone a repository locally - -To clone a repository, run the **Git: Clone** command in the Command Palette (`kb(workbench.action.showCommands)`), or select the **Clone Repository** button in the **Source Control** view. - -If you clone from GitHub, VS Code prompts you to authenticate with GitHub. Then, select a repository from the list to clone to your machine. The list contains both public and private repositories. - -![Screenshot of the Clone Repository quick prompt, searching for repositories with the name vscode](images/intro/github-clone.png) - -For other Git providers, enter the repository URL, select **Clone**, and pick a folder on your local machine to clone the files into. VS Code opens the folder once the repository is cloned on your local machine. - -![Screenshot of the Clone Repository quick prompt, searching for a repository by providing the repository URL](images/intro/git-clone-repository-url.png) - -### Initialize a repository in a local folder - -To initialize a new local Git repository: - -1. Pick an existing or new folder on your computer and open it in VS Code. - -1. In the **Source Control** view, select the **Initialize Repository** button. - - This creates a new Git repository in the current folder, allowing you to start tracking code changes. - - This action is equivalent to running `git init` on the command-line. - - ![Source Control view for a workspace not under Git source control will offer to Initialize a Git repo or Publish to GitHub](images/intro/scm-init-publish.png) - -#### Publish local repository to GitHub - -You can also initialize a local repository and publish it directly to GitHub. This creates a new repository on your GitHub account, and pushes your local code changes to the remote repository. Having your source code on a remote repository is a great way to back up your code, collaborate with others, and automate your workflow with [GitHub Actions](https://github.com/features/actions). - -Use the **Publish to GitHub** command button in the **Source Control** view. You can then choose a name and description for the repository, and whether to make it public or private. - -![Screenshot of the Publish to GitHub quick prompt, showing private and public GitHub repository names](images/intro/publish-to-github.png) - -Once the repository has been created, VS Code pushes your local code to the remote repository. Your code is now backed up on GitHub, and you can start collaborating with others with commits and pull requests. - -### Open a GitHub repository in a codespace - -[GitHub Codespaces](https://github.com/features/codespaces) lets you open a GitHub repository in a fully configured cloud-based development environment, enabling you to develop in a browser without having to install any software on your local computer. GitHub Codespaces allows free usage for individuals, which makes it easy to get started working on open source projects. - -To create a codespace for your GitHub repository: - -1. Install the [GitHub Codespaces](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) extension in VS Code and sign in with your GitHub account. - -1. Run the **Codespaces: Create New Codespace** command. - -1. Select the repository and branch you want to open. - - VS Code opens a new window, which is connected to the codespace. The source code, terminal, and running and debugging are hosted in the remote cloud-based development environment. - - Notice that the File Explorer and Status Bar indicate that the workspace is opened in a codespace. - - ![Screenshot of a workspace opened in a codespace, highlighting the codespace name in the File Explorer and Status Bar](images/intro/open-workspace-in-codespace.png) - -Alternatively, you can also start from a codespace template on the [GitHub Codespaces website](https://github.com/codespaces/templates). - -If you already have a codespace open in your browser, run the **Codespaces: Open in VS Code Desktop** command in the browser to connect to the codespace from your local VS Code Desktop. - -You can learn more about GitHub Codespaces, including customization such as forwarding ports, in the [Developing in a codespace](https://docs.github.com/codespaces/developing-in-codespaces/developing-in-a-codespace?tool=vscode) documentation. - -### Open a GitHub repository remotely - -VS Code's remote repository support allows you to browse and edit a GitHub repository without cloning it to your local computer. This is useful for quickly making changes to a remote repository without having to clone the entire codebase to your machine. - -1. First install the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=GitHub.remotehub) extension. - -1. Run the command **Remote Repositories: Open Remote Repository...** or use the **Open Remote Repository** button the Explorer view. - -1. Search and select the GitHub repository that you want to open. - - ![Remote Repositories opening a remote GitHub repo, pull request or Azure repo](images/intro/remote-repo.png) - -> [!TIP] -> If you need to execute code or run terminal commands, you can seamlessly switch from a remote repository to a codespace with the command **Continue Working on**. - -## Staging and committing code changes - -Once you have a Git repository set up, you can start tracking code changes by [staging and committing](https://git-scm.com/about/staging-area) your newly created and edited code. - -> [!TIP] -> Commit your changes early and often. This makes it easier to revert back to previous versions of your code if needed. - -You can access the **Source Control** view from the Activity Bar to list all changed files in your workspace. You can toggle between a tree view or list view by using the tree/list icon in the Source Control view header. - -![Source Control view, highlighting the tree/list view control in the header](images/intro/source-control-view.png) - -When you select a file in the Source Control view, the editor shows a diff view that highlights the file changes, compared to the previously committed file. - -![Source Control view with one file staged and other changes, a diff showing in the editor that highlights the changes](images/intro/scm-staging.png) - -To stage a file, select the **+** (plus) icon next to the file in the **Source Control** view. This adds the file to the **Staged Changes** section, indicating that it will be included in the next commit. - -![Source Control view with four changed files, highlighting the '+' button to stage the changes of a file](images/intro/scm-stage-changes.png) - -You can also stage all pending changes at once by selecting the **+** (plus) icon next to **Changes** in the Source Control view. - -Staged changes can also be discarded by selecting the **−** (minus) icon next to the file. Similarly, you can discard all staged changes by selecting the **−** (minus) icon next to **Staged Changes** in the Source Control view. - -![Source Control view with four changed files, highlighting the '-' button to unstage the changes of a file](images/intro/scm-unstage-changes.png) - -To commit your staged changes, type a commit message in the upper text box, and then select the **Commit** button. This saves your changes to the local Git repository, allowing you to revert to previous versions of your code if needed. - -> [!TIP] -> With GitHub Copilot in VS Code, you can [generate a commit message](/docs/copilot/overview.md#productivity-improvements) based on your code changes. Learn more about [generating commit messages with AI](/docs/sourcecontrol/overview.md#generate-a-commit-message-with-ai). Before you commit your changes, you can also let Copilot do a [code review of the uncommitted changes](/docs/sourcecontrol/overview.md#review-uncommitted-code-changes-with-ai). - -You can navigate through and review all local file changes and commits in the **Timeline** view available in the bottom of the Explorer view. - -![Timeline view with one item selected and its change being shown in the editor](images/intro/timeline.png) - -## Pushing and pulling remote changes - -Once you have made commits to your local Git repository, you can push them to the remote repository. The **Sync Changes** button indicates how many commits are going to be pushed and pulled. Selecting the **Sync Changes** button downloads (pull) any new remote commits and uploads (push) new local commits to the remote repository. - -![Sync button with one change to push](images/intro/sync.png) - -> [!TIP] -> You can enable the **Git: Autofetch** [setting](/docs/configure/settings.md) to always get an up-to-date remote commit indicator. - -Push and pull can also be performed individually by using their respective commands. You can access these commands from the Source Control menu. - -![Source Control menu that shows all source control commands](images/intro/scm-menu.png) - -## Using branches - -In Git, [branches](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) allow you to work on multiple versions of your codebase simultaneously. This is useful for experimenting with new features or making large code changes without affecting the main codebase. - -The branch indicator in the Status bar shows the current branch and lets you switch to new and existing branches. - -![Branch indicator in the Status bar](images/intro/branch-indicator.png) - -To create a new branch, select the branch indicator and choose to create it from the current branch or another local one. Type a name for the new branch, and confirm. VS Code creates a new branch and switches to it, allowing you to make changes to your code without affecting the main branch. - -![Create branch quick prompt that shows when selecting the branch indicator](images/intro/scm-create-branch.png) - -> [!TIP] -> If you use the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension, you can create a branch directly from an issue, which gets you started working in a new local branch and automatically prefills the pull request for you. - -After you create a local branch, you can push the branch to the remote repository by selecting **Publish Branch** in the **Source Control** view. This creates a new branch on the remote repository, allowing you to collaborate with others in that branch. - -### Creating and reviewing GitHub pull requests - -In Git and GitHub, [pull requests (PRs)](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) are a way for collaborators to review and merge code changes from separate branches into the main branch. This enables teams to review and approve code changes before they are incorporated into the main codebase, ensuring that only high-quality changes are merged. - -To use pull requests in VS Code, you need to install the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension. This extension adds PR and issue tracking functionality to VS Code, allowing you to create, review, and merge PRs from within the editor. - -To create a PR, make sure you are on a separate branch from the main branch, and push your code changes to the remote repository. In the **Source Control** view, select the **Create Pull Request** button. This opens the PR creation form, where you can enter a title and description for the PR, and choose which branch to merge the changes into. Select **Create** to create the PR. - -![Source Control view, highlighting the 'Create pull request' button](images/intro/scm-create-pull-request.png) - -> [!TIP] -> Use GitHub Copilot to generate a PR title and description, based on the commits that are included in the PR. Select the _sparkle_ icon next to the PR title field to generate a PR title and description. You can also [let Copilot perform a code review of the PR]() before you create it. Select the **Code Review** button in the GitHub Pull Request view. - -Learn more about pull requests in [VS Code's GitHub documentation](/docs/sourcecontrol/github.md). - -## Using Git in the built-in terminal - -As all Git state is kept in the local repository, you can easily switch between VS Code's UI, the [built-in terminal](/docs/terminal/basics.md), or external tools like [GitHub Desktop](https://desktop.github.com). You can also set up [VS Code as your default Git editor](/docs/sourcecontrol/overview.md#vs-code-as-git-editor), allowing you to use VS Code to edit commit messages and other Git-related files. - -### Git Bash on Windows - -Git Bash is a popular shell environment for Windows that provides a Unix-like command-line interface for working with Git and other command-line tools. Visual Studio Code's integrated terminal supports Git Bash as a shell, allowing you to seamlessly integrate Git Bash into your development workflow. Installing Git on your Windows machine also installs Git Bash, if it wasn't deselected during the installation steps. - -![Selecting Git Bash as shell in Visual Studio Code's built-in terminal](images/intro/git-bash.png) - -Start by opening **View** > **Terminal** (`kb(workbench.action.terminal.toggleTerminal)`). Select the dropdown arrow next to the `+` icon in the terminal panel to pick a new shell to open. If Git Bash is installed, it's shown in the list of terminals and shells. You can toggle between different terminals and shells in the Terminal sidebar. With Git Bash configured in Visual Studio Code, you can now use all of your favorite Git commands directly from the terminal in your code editor. - -If you want to set Git Bash as your default shell, open the Terminal dropdown (next to the `+` icon) and select **Select Default Profile**. This opens a list of available shells, including Git Bash. Selecting *Git Bash* sets it as your default shell, and all future terminals will be opened with Git Bash. More advanced terminal tips are available in the [terminal documentation](/docs/terminal/basics.md). diff --git a/docs/sourcecontrol/merge-conflicts.md b/docs/sourcecontrol/merge-conflicts.md index 6668380075..a34a2c3224 100644 --- a/docs/sourcecontrol/merge-conflicts.md +++ b/docs/sourcecontrol/merge-conflicts.md @@ -1,6 +1,6 @@ --- ContentId: 8f4e9d2a-3b5c-4e7a-9f1d-2c8a5b6e3d9f -DateApproved: 11/24/2025 +DateApproved: 11/12/2025 MetaDescription: Learn how to resolve Git merge conflicts in VS Code using inline editor actions, the 3-way merge editor, and AI-assisted resolution. --- # Resolve merge conflicts in VS Code @@ -19,6 +19,9 @@ A merge conflict happens when Git encounters competing changes that it cannot au When you attempt to merge, rebase, pull, or cherry-pick commits that contain conflicting changes, Git pauses the operation and marks the conflicts for you to resolve manually. +> [!TIP] +> Learn more about [creating and managing branches](/docs/sourcecontrol/branches-worktrees.md) to organize your development work and minimize merge conflicts. + ## Recognize conflicts in VS Code When merge conflicts occur, VS Code provides multiple visual indicators to help you identify and resolve them. Files with conflicts appear in the Source Control view under a **Merge Changes** section. @@ -160,6 +163,7 @@ git config --global mergetool.vscode.cmd 'code --wait $MERGED' ## Next steps +* [Branches and Worktrees](/docs/sourcecontrol/branches-worktrees.md) - Learn about branch management and strategies to minimize conflicts * [Staging and Committing](/docs/sourcecontrol/staging-commits.md) - Learn about staging changes and creating commits * [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about working with remote repositories * [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features in VS Code diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index 73b6356117..74675ad230 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -120,6 +120,8 @@ To work with multiple branches simultaneously, you can use Git worktrees to crea Temporarily save uncommitted changes when you need to switch contexts quickly by using a Git stash: save, view, apply, or pop your stashed changes directly from the Source Control view. +Learn more about [working with branches and worktrees](/docs/sourcecontrol/branches-worktrees.md). + ### View commit history It can be helpful to review the commit history to understand how your code has changed over time. @@ -157,6 +159,7 @@ Browse available SCM provider extensions in the Extensions view (`kb(workbench.v * [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support +* [Branches and Worktrees](/docs/sourcecontrol/branches-worktrees.md) - Learn about branch management, Git worktrees, and stash operations * [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues in VS Code * [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered features beyond Git workflows diff --git a/docs/sourcecontrol/quickstart.md b/docs/sourcecontrol/quickstart.md index dfd97878ba..3ed7d1b05d 100644 --- a/docs/sourcecontrol/quickstart.md +++ b/docs/sourcecontrol/quickstart.md @@ -1,6 +1,6 @@ --- ContentId: 5f83254d-2817-4398-9321-456789abcdef -DateApproved: 11/19/2025 +DateApproved: 11/12/2025 MetaDescription: Quickly get started with Git source control in Visual Studio Code. Initialize a repository, stage changes, and commit code in minutes. --- # Quickstart: use source control in VS Code @@ -145,6 +145,7 @@ If your repository is connected to a remote server (for example, GitHub or Azure Now that you know the basics, explore more features: +* [Branches and Worktrees](/docs/sourcecontrol/branches-worktrees.md) - Learn about branch management and parallel development. * [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories. * [Resolve Merge Conflicts](/docs/sourcecontrol/merge-conflicts.md) - Learn how to handle conflicts when merging branches. * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about Pull Requests and Issues. diff --git a/docs/sourcecontrol/repos-remotes.md b/docs/sourcecontrol/repos-remotes.md index cac2cde7d2..0fcd5be6ea 100644 --- a/docs/sourcecontrol/repos-remotes.md +++ b/docs/sourcecontrol/repos-remotes.md @@ -232,7 +232,7 @@ Credential helpers securely store your authentication credentials so you don't h ## Next steps -* [Source Control Overview](/docs/sourcecontrol/overview.md) - Learn about other Git features in VS Code +* [Branches and Worktrees](/docs/sourcecontrol/branches-worktrees.md) - Learn about branch management and parallel development * [Staging and Committing](/docs/sourcecontrol/staging-commits.md) - Master the commit workflow +* [Merge Conflicts](/docs/sourcecontrol/merge-conflicts.md) - Handle conflicts when merging branches * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn about pull requests and GitHub integration -* [Introduction to Git](/docs/sourcecontrol/intro-to-git.md) - Understand Git concepts and terminology diff --git a/docs/sourcecontrol/staging-commits.md b/docs/sourcecontrol/staging-commits.md index 08688a3e3a..4d29ce2f89 100644 --- a/docs/sourcecontrol/staging-commits.md +++ b/docs/sourcecontrol/staging-commits.md @@ -234,7 +234,8 @@ Learn more about the [Timeline view](/docs/getstarted/userinterface.md#timeline- ## Next steps +* [Branches and Worktrees](/docs/sourcecontrol/branches-worktrees.md) - Learn about branch management, Git worktrees, and stash operations * [Repositories and Remotes](/docs/sourcecontrol/repos-remotes.md) - Learn about cloning, publishing, and syncing with remote repositories -* [Source Control Overview](/docs/sourcecontrol/overview.md) - Explore other Git features like branching and merging +* [Merge Conflicts](/docs/sourcecontrol/merge-conflicts.md) - Handle conflicts when merging branches * [Working with GitHub](/docs/sourcecontrol/github.md) - Learn how to work with pull requests and issues * [Copilot in VS Code](/docs/copilot/overview.md) - Discover more AI-powered development features diff --git a/docs/toc.json b/docs/toc.json index aa716bea0e..b0c39f653f 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -171,8 +171,8 @@ "topics": [ ["Overview", "/docs/sourcecontrol/overview"], ["Quickstart", "/docs/sourcecontrol/quickstart"], - ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], ["Staging & Committing", "/docs/sourcecontrol/staging-commits"], + ["Branches & Worktrees", "/docs/sourcecontrol/branches-worktrees"], ["Repositories & Remotes", "/docs/sourcecontrol/repos-remotes"], ["Merge Conflicts", "/docs/sourcecontrol/merge-conflicts"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], From f28a96f70b85ac3f6e050c2dadb71bce2a21e048 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Mon, 24 Nov 2025 19:03:14 +0100 Subject: [PATCH 08/12] Edit pass --- docs/sourcecontrol/github.md | 56 +++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/docs/sourcecontrol/github.md b/docs/sourcecontrol/github.md index 6b671a277c..34db8e3e03 100644 --- a/docs/sourcecontrol/github.md +++ b/docs/sourcecontrol/github.md @@ -7,11 +7,27 @@ MetaDescription: Working with GitHub Pull Requests and Issues in Visual Studio C [GitHub](https://github.com) is a cloud-based service for storing and sharing source code. Using GitHub with Visual Studio Code lets you share your source code and collaborate with others right within your editor. There are many ways to interact with GitHub, for example, via their website at [https://github.com](https://github.com) or the [Git](https://git-scm.com) command-line interface (CLI), but in VS Code, the rich GitHub integration is provided by the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension. -Install the GitHub Pull Requests and Issues extension +In this topic, we'll demonstrate how you can use some of your favorite parts of GitHub without leaving VS Code. -To get started with the GitHub in VS Code, you'll need to install [Git](https://git-scm.com/download), [create a GitHub account](https://docs.github.com/get-started/signing-up-for-github/signing-up-for-a-new-github-account) and install the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension. In this topic, we'll demonstrate how you can use some of your favorite parts of GitHub without leaving VS Code. +> [!TIP] +> If you're new to source control or want to learn more about VS Code's basic Git support, you can start with the [Source Control](/docs/sourcecontrol/overview.md) topic. + +## Prerequisites + +To get started with GitHub in VS Code, you need: + +* VS Code uses your machine's Git installation. [Install Git version 2.0.0 or later](https://git-scm.com/download) on your machine. + +* A [GitHub account](https://docs.github.com/get-started/signing-up-for-github/signing-up-for-a-new-github-account). + +* The [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension installed in VS Code. + +* When you commit changes, Git uses your configured username and email. You can set these values with: -If you're new to source control or want to learn more about VS Code's basic Git support, you can start with the [Source Control](/docs/sourcecontrol/overview.md) topic. + ```bash + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` ## Getting started with GitHub Pull Requests and Issues @@ -19,7 +35,7 @@ Once you've installed the [GitHub Pull Requests and Issues](https://marketplace. ![Extension Sign In](images/github/extension-signin.png) -If you are not redirected to VS Code, you can add your authorization token manually. In the browser window, you will receive your authorization token. Copy the token, and switch back to VS Code. Select **Signing in to github.com...** in the Status bar, paste the token, and hit `kbstyle(Enter)`. +If you are not redirected to VS Code, you can add your authorization token manually. In the browser window, you will receive your authorization token. Copy the token, and switch back to VS Code. Select **Signing in to github.com...** in the Status Bar, paste the token, and press `kbstyle(Enter)`. ## Setting up a repository @@ -113,9 +129,9 @@ Once you select **Create**, if you have not already pushed your branch to a GitH The **Create Pull Request** view now enters **Review Mode**, where you can review the details of the PR, add comments, and merge the PR once it's ready. After the PR is merged, you'll have the option to delete both the remote and local branch. > [!TIP] -> Use GitHub Copilot to generate a PR title and description, based on the commits that are included in the PR. Select the _sparkle_ icon next to the PR title field to generate a PR title and description. +> Use AI to generate a PR title and description, based on the commits that are included in the PR. Select the _sparkle_ icon next to the PR title field to generate a PR title and description. -![Screenshot that shows the Generate Commit Message with Copilot button in the commit message input box.](images/overview/copilot-generate-commit-message.png) +![Screenshot that shows the Generate Commit Message in the commit message input box.](images/overview/copilot-generate-commit-message.png) ### Reviewing @@ -123,7 +139,7 @@ Pull requests can be reviewed from the **Pull Requests** view. You can assign re ![Pull Request Description editor](images/github/pull-request-description-editor.png) -From the **Description** page, you can also easily checkout the pull request locally using the **Checkout** button. This will switch VS Code to open the fork and branch of the pull request (visible in the Status bar) in Review Mode and add a new **Changes in Pull Request** view from which you can view diffs of the current changes as well as all commits and the changes within these commits. Files that have been commented on are decorated with a diamond icon. To view the file on disk, you can use the **Open File** inline action. +From the **Description** page, you can also easily checkout the pull request locally using the **Checkout** button. This will switch VS Code to open the fork and branch of the pull request (visible in the Status Bar) in Review Mode and add a new **Changes in Pull Request** view from which you can view diffs of the current changes as well as all commits and the changes within these commits. Files that have been commented on are decorated with a diamond icon. To view the file on disk, you can use the **Open File** inline action. ![Changes in Pull Request view](images/github/changes-view.png) @@ -132,7 +148,7 @@ The diff editors from this view use the local file, so file navigation, IntelliS When you are done reviewing the pull request changes you can merge the PR or select **Exit Review Mode** to go back to the previous branch you were working on. > [!TIP] -> You can also [let Copilot perform a code review of the PR](https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review?tool=vscode) before you create it. Select the **Code Review** button in the GitHub Pull Request view. +> You can also [use AI to perform a code review of the PR](https://docs.github.com/en/copilot/using-github-copilot/code-review/using-copilot-code-review?tool=vscode) before you create it. Select the **Code Review** button in the GitHub Pull Request view. ## Issues @@ -163,13 +179,13 @@ From the **Issues** view, you can see your issues and work on them. ![Issue view with hover](images/github/issues-view.png) -By default, when you start working on an issue (**Start Working on Issue** context menu item), a branch will be created for you, as shown in the Status bar in the image below. +By default, when you start working on an issue (**Start Working on Issue** context menu item), a branch will be created for you, as shown in the Status Bar in the image below. ![Work on Issue](images/github/working-on-issue.png) -The Status bar also shows the active issue and if you select that item, a list of issue actions are available such as opening the issue on the GitHub website or creating a pull request. +The Status Bar also shows the active issue and if you select that item, a list of issue actions are available such as opening the issue on the GitHub website or creating a pull request. -![Issue Status bar actions](images/github/issue-status-bar-actions.png) +![Issue Status Bar actions](images/github/issue-status-bar-actions.png) You can configure the name of the branch using the **GitHub Issues: Issue Branch Title** (`setting(githubIssues.issueBranchTitle)`) setting. If your workflow doesn't involve creating a branch, or if you want to be prompted to enter a branch name every time, you can skip that step by turning off the **GitHub Issues: Use Branch For Issues** (`setting(githubIssues.useBranchForIssues)`) setting. @@ -186,9 +202,9 @@ The [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=gi ### Opening a repository -Once you have installed the GitHub Repositories extension, you can open a repository with the **GitHub Repositories: Open Repository...** command from the Command Palette (`kb(workbench.action.showCommands)`) or by clicking the Remote indicator in the lower left of the Status bar. +Once you have installed the GitHub Repositories extension, you can open a repository with the **GitHub Repositories: Open Repository...** command from the Command Palette (`kb(workbench.action.showCommands)`) or by clicking the Remote indicator in the lower left of the Status Bar. -![Remote indicator in the Status bar](images/github/remote-indicator.png) +![Remote indicator in the Status Bar](images/github/remote-indicator.png) When you run the **Open Repository** command, you then choose whether to open a repository from GitHub, open a Pull Request from GitHub, or reopen a repository that you had previously connected to. @@ -208,9 +224,9 @@ The GitHub Repositories extension supports viewing and even committing LFS-track ### Switching branches -You can easily switch between branches by clicking on the branch indicator in the Status bar. One great feature of the GitHub Repositories extension is that you can switch branches without needing to stash uncommitted changes. The extension remembers your changes and reapplies them when you switch branches. +You can easily switch between branches by clicking on the branch indicator in the Status Bar. One great feature of the GitHub Repositories extension is that you can switch branches without needing to stash uncommitted changes. The extension remembers your changes and reapplies them when you switch branches. -![Branch indicator on the Status bar](images/github/branch-indicator-status-bar.png) +![Branch indicator on the Status Bar](images/github/branch-indicator-status-bar.png) ### Remote Explorer @@ -218,7 +234,7 @@ You can quickly reopen remote repositories with the Remote Explorer available on ![Remote Explorer view](images/github/github-remote-explorer.png) -### Create Pull Requests +### Create pull requests If your workflow uses Pull Requests, rather than direct commits to a repository, you can create a new PR from the Source Control view. You'll be prompted to provide a title and create a new branch. @@ -234,7 +250,7 @@ Without a repository's files on your local machine, the GitHub Repositories exte Extension authors can learn more about running in a virtual file system and workspace in the [Virtual Workspaces extension author's guide](https://github.com/microsoft/vscode/wiki/Virtual-Workspaces). -### Continue Working On... +### Continue working on Sometimes you'll want to switch to working on a repository in a development environment with support for a local file system and full language and development tooling. The GitHub Repositories extension makes it easy for you to: @@ -242,11 +258,11 @@ Sometimes you'll want to switch to working on a repository in a development envi * Clone the repository locally. * Clone the repository into a Docker container (if you have [Docker](https://docker.com/) and the Microsoft [Container Tools extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) installed). -To switch development environments, use the **Continue Working On...** command, available from the Command Palette (`kb(workbench.action.showCommands)`) or by clicking on the Remote indicator in the Status bar. +To switch development environments, use the **Continue Working On** command, available from the Command Palette (`kb(workbench.action.showCommands)`) or by clicking on the Remote indicator in the Status Bar. ![Continue Working On command in Remote dropdown](images/github/continue-working.png) -If you are using the [browser-based editor](/docs/remote/codespaces.md#browserbased-editor), the **"Continue Working On..."** command has the options to open the repository locally or within a cloud-hosted environment in [GitHub Codespaces](https://github.com/features/codespaces). +If you are using the [browser-based editor](/docs/remote/codespaces.md#browserbased-editor), the **"Continue Working On"** command has the options to open the repository locally or within a cloud-hosted environment in [GitHub Codespaces](https://github.com/features/codespaces). ![Continue Working On from web-based editor](images/github/codespaces-continue.png) @@ -258,4 +274,4 @@ In the event that your pending changes are not automatically applied to your tar ## Next steps -* Learn more about [Copilot VS Code](/docs/copilot/overview.md) - Learn about Copilot in VS Code. +* Learn more about [AI in VS Code](/docs/copilot/overview.md) - Learn about AI features in VS Code. From ac316f382265d53e412b57de9052e33f2a428c44 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Mon, 24 Nov 2025 19:14:59 +0100 Subject: [PATCH 09/12] Add search keywords --- docs/sourcecontrol/branches-worktrees.md | 5 +++++ docs/sourcecontrol/faq.md | 5 +++++ docs/sourcecontrol/github.md | 5 +++++ docs/sourcecontrol/merge-conflicts.md | 5 +++++ docs/sourcecontrol/overview.md | 5 +++++ docs/sourcecontrol/quickstart.md | 5 +++++ docs/sourcecontrol/repos-remotes.md | 5 +++++ docs/sourcecontrol/staging-commits.md | 5 +++++ 8 files changed, 40 insertions(+) diff --git a/docs/sourcecontrol/branches-worktrees.md b/docs/sourcecontrol/branches-worktrees.md index 7346849434..aa0a65a764 100644 --- a/docs/sourcecontrol/branches-worktrees.md +++ b/docs/sourcecontrol/branches-worktrees.md @@ -2,6 +2,11 @@ ContentId: a9b2c3d4-e5f6-7890-ab12-cd3456789012 DateApproved: 11/12/2025 MetaDescription: Learn how to work with Git branches and worktrees in VS Code. Create, switch between, and manage multiple branches, use Git worktrees for parallel development, and manage stashes for temporary changes. +Keywords: +- source control +- scm +- version control +- git --- # Git Branches and Worktrees in VS Code diff --git a/docs/sourcecontrol/faq.md b/docs/sourcecontrol/faq.md index b48fe80a49..57ab9b7307 100644 --- a/docs/sourcecontrol/faq.md +++ b/docs/sourcecontrol/faq.md @@ -2,6 +2,11 @@ ContentId: 431b4458-34c4-4aba-a0ee-eaddf7cd91a1 MetaDescription: Visual Studio Code's Frequently Asked Questions (FAQ) for Source Control, Git & GitHub in VS Code DateApproved: 11/12/2025 +Keywords: +- source control +- scm +- version control +- git --- # Source Control FAQ diff --git a/docs/sourcecontrol/github.md b/docs/sourcecontrol/github.md index 34db8e3e03..315279b90e 100644 --- a/docs/sourcecontrol/github.md +++ b/docs/sourcecontrol/github.md @@ -2,6 +2,11 @@ ContentId: bd1be8cf-b745-4737-be48-db381ec3acc6 DateApproved: 11/12/2025 MetaDescription: Working with GitHub Pull Requests and Issues in Visual Studio Code +Keywords: +- source control +- scm +- version control +- git --- # Working with GitHub in VS Code diff --git a/docs/sourcecontrol/merge-conflicts.md b/docs/sourcecontrol/merge-conflicts.md index a34a2c3224..d93b644d32 100644 --- a/docs/sourcecontrol/merge-conflicts.md +++ b/docs/sourcecontrol/merge-conflicts.md @@ -2,6 +2,11 @@ ContentId: 8f4e9d2a-3b5c-4e7a-9f1d-2c8a5b6e3d9f DateApproved: 11/12/2025 MetaDescription: Learn how to resolve Git merge conflicts in VS Code using inline editor actions, the 3-way merge editor, and AI-assisted resolution. +Keywords: +- source control +- scm +- version control +- git --- # Resolve merge conflicts in VS Code diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index 74675ad230..b5e1e3acd7 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -2,6 +2,11 @@ ContentId: 7E22CCC0-2AB8-4729-A4C9-BE2B16853820 DateApproved: 11/12/2025 MetaDescription: Learn how to use VS Code's integrated Git source control features like staging, committing, branching, merge conflict resolution, and GitHub integration. +Keywords: +- source control +- scm +- version control +- git --- # Source Control in VS Code diff --git a/docs/sourcecontrol/quickstart.md b/docs/sourcecontrol/quickstart.md index 3ed7d1b05d..ce7bc68ef7 100644 --- a/docs/sourcecontrol/quickstart.md +++ b/docs/sourcecontrol/quickstart.md @@ -2,6 +2,11 @@ ContentId: 5f83254d-2817-4398-9321-456789abcdef DateApproved: 11/12/2025 MetaDescription: Quickly get started with Git source control in Visual Studio Code. Initialize a repository, stage changes, and commit code in minutes. +Keywords: +- source control +- scm +- version control +- git --- # Quickstart: use source control in VS Code diff --git a/docs/sourcecontrol/repos-remotes.md b/docs/sourcecontrol/repos-remotes.md index 0fcd5be6ea..2ffee785b0 100644 --- a/docs/sourcecontrol/repos-remotes.md +++ b/docs/sourcecontrol/repos-remotes.md @@ -2,6 +2,11 @@ ContentId: 8f34d9b6-3185-426a-b6d9-7e5ac7138a31 DateApproved: 11/12/2025 MetaDescription: Master working with Git repositories and remotes in VS Code. Learn about cloning, publishing, push/pull/sync operations, upstream tracking, auto-fetch, and managing multiple repositories. +Keywords: +- source control +- scm +- version control +- git --- # Working with repositories and remotes diff --git a/docs/sourcecontrol/staging-commits.md b/docs/sourcecontrol/staging-commits.md index 4d29ce2f89..31c1666127 100644 --- a/docs/sourcecontrol/staging-commits.md +++ b/docs/sourcecontrol/staging-commits.md @@ -2,6 +2,11 @@ ContentId: 344271ac-56df-4cea-b0a9-2c135f7f3dec DateApproved: 11/12/2025 MetaDescription: Master Git staging and commits in VS Code with granular file control, AI-powered commit messages, visual diff reviews, and comprehensive change tracking tools. +Keywords: +- source control +- scm +- version control +- git --- # Staging and committing changes From c8a9a60d96429c75b37e06f1d7d580e6939b0206 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Tue, 25 Nov 2025 10:54:51 +0100 Subject: [PATCH 10/12] Edit pass --- docs/sourcecontrol/github.md | 50 +++++++++++-------- .../images/github/extension-signin.png | 4 +- 2 files changed, 31 insertions(+), 23 deletions(-) diff --git a/docs/sourcecontrol/github.md b/docs/sourcecontrol/github.md index 315279b90e..99515e703e 100644 --- a/docs/sourcecontrol/github.md +++ b/docs/sourcecontrol/github.md @@ -21,7 +21,7 @@ In this topic, we'll demonstrate how you can use some of your favorite parts of To get started with GitHub in VS Code, you need: -* VS Code uses your machine's Git installation. [Install Git version 2.0.0 or later](https://git-scm.com/download) on your machine. +* Git is installed on your computer. [Install Git version 2.0.0 or later](https://git-scm.com/download) on your machine. * A [GitHub account](https://docs.github.com/get-started/signing-up-for-github/signing-up-for-a-new-github-account). @@ -36,11 +36,20 @@ To get started with GitHub in VS Code, you need: ## Getting started with GitHub Pull Requests and Issues -Once you've installed the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension, you'll need to sign in. Follow the prompts to authenticate with GitHub in the browser and return to VS Code. +Once you've installed the [GitHub Pull Requests and Issues](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension, you'll need to sign in. -![Extension Sign In](images/github/extension-signin.png) +1. Select the GitHub icon in the Activity Bar +1. Select **Sign In** and follow the prompts to authenticate with GitHub in the browser -If you are not redirected to VS Code, you can add your authorization token manually. In the browser window, you will receive your authorization token. Copy the token, and switch back to VS Code. Select **Signing in to github.com...** in the Status Bar, paste the token, and press `kbstyle(Enter)`. + ![Screenshot of the GitHub view, showing the sign in button.](images/github/extension-signin.png) + +1. You should be redirected back to VS Code + +If you are not redirected to VS Code, you can add your authorization token manually: + +1. In the browser window, copy your authorization token +1. In VS Code, select **Signing in to github.com...** in the Status Bar +1. Paste the token and press `kbstyle(Enter)` to complete the sign-in process ## Setting up a repository @@ -48,11 +57,9 @@ If you are not redirected to VS Code, you can add your authorization token manua You can search for and clone a repository from GitHub using the **Git: Clone** command in the Command Palette (`kb(workbench.action.showCommands)`) or by using the **Clone Repository** button in the Source Control view (available when you have no folder open). -![Clone Repository button in the Source Control view](images/github/git-clone-button.png) - From the GitHub repository dropdown you can filter and pick the repository you want to clone locally. -![GitHub repository dropdown filtered on microsoft/vscode](images/github/github-repo-dropdown.png) +![Screenshot showing the GitHub repository Quick Pick filtered on microsoft/vscode.](images/github/github-repo-dropdown.png) Learn more about [cloning repositories and working with remotes](/docs/sourcecontrol/repos-remotes.md#clone-repositories). @@ -60,37 +67,38 @@ Learn more about [cloning repositories and working with remotes](/docs/sourcecon Enabling authentication through GitHub happens when you run any Git action in VS Code that requires GitHub authentication, such as pushing to a repository that you're a member of or cloning a private repository. You don't need to have any special extensions installed for authentication; it is built into VS Code so that you can efficiently manage your repository. -When you do something that requires GitHub authentication, you'll see a prompt to sign in: +When you perform an action that requires GitHub authentication, VS Code prompts you to sign in. Follow the steps to sign into GitHub and return to VS Code. -![Authentication Prompt](images/github/auth-prompt.png) +![Screenshot showing the GitHub authentication dialog.](images/github/auth-prompt.png) -Follow the steps to sign into GitHub and return to VS Code. Signing in with a personal access token (PAT) is only supported with GitHub Enterprise Server. If you're using GitHub Enterprise Server and want to use a PAT, then you can hit "cancel" on the sign in prompts until you are prompted for a PAT. +Signing in with a personal access token (PAT) is only supported with GitHub Enterprise Server. If you're using GitHub Enterprise Server and want to use a PAT, you can select **Cancel** on the sign in prompts until you are prompted for a PAT. Note that there are several ways to authenticate to GitHub, including using your username and password with two-factor authentication (2FA), a personal access token, or an SSH key. See [About authentication to GitHub](https://docs.github.com/github/authenticating-to-github/about-authentication-to-github) for more information and details about each option. ->**Note**: If you'd like to work on a repository without cloning the contents to your local machine, you can install the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=github.remotehub) extension to browse and edit directly on GitHub. You can learn more below in the [GitHub Repositories extension](/docs/sourcecontrol/github.md#github-repositories-extension) section. +> [!NOTE] +> If you'd like to work on a repository without cloning the contents to your local machine, you can install the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=github.remotehub) extension to browse and edit directly on GitHub. Learn more about the [GitHub Repositories extension](/docs/sourcecontrol/github.md#github-repositories-extension). ## Editor integration ### Hovers -When you have a repository open and a user is @-mentioned, you can hover over that username and see a GitHub-style hover. +When you have a repository open and a user is @-mentioned (for example, in a code comment), you can hover over that username and see a GitHub-style hover with the user's details. -![User Hover](images/github/user-hover.png) +![Screenshot showing a user hover for a @-mentioned user in a code comment.](images/github/user-hover.png) There is a similar hover for #-mentioned issue numbers, full GitHub issue URLs, and repository specified issues. -![Issue Hover](images/github/issue-hover.png) +![Screenshot showing a hover for a #-mentioned issue number in a code comment.](images/github/issue-hover.png) ### Suggestions -User suggestions are triggered by the "@" character and issue suggestions are triggered by the "#" character. Suggestions are available in the editor and in the **Source Control** view's input box. +User suggestions are triggered by typing the "@" character and issue suggestions are triggered by typing the "#" character. Suggestions are available in the editor and in the Source Control commit message input box. -![User and Issue suggestions](images/github/user-issue-suggest.gif) +![GIF showing User and Issue suggestions in the editor.](images/github/user-issue-suggest.gif) -The issues that appear in the suggestion can be configured with the **GitHub Issues: Queries** (`setting(githubIssues.queries)`) [setting](/docs/configure/settings.md). The queries use the [GitHub search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). +The issues that appear in the suggestion can be configured with the **GitHub Issues: Queries** (`setting(githubIssues.queries)`) setting. The queries use the [GitHub search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). -You can also configure which files show these suggestions using the settings **GitHub Issues: Ignore Completion Trigger** (`setting(githubIssues.ignoreCompletionTrigger)`) and **GitHub Issues: Ignore User Completion Trigger** (`setting(githubIssues.ignoreUserCompletionTrigger)`). These settings take an array of [language identifiers](/docs/languages/identifiers.md) to specify the file types. +You can also configure which file types show these suggestions by using the settings **GitHub Issues: Ignore Completion Trigger** (`setting(githubIssues.ignoreCompletionTrigger)`) and **GitHub Issues: Ignore User Completion Trigger** (`setting(githubIssues.ignoreUserCompletionTrigger)`). These settings take an array of [language identifiers](/docs/languages/identifiers.md) to specify the file types. ```jsonc // Languages that the '#' character should not be used to trigger issue completion suggestions. @@ -103,7 +111,7 @@ You can also configure which files show these suggestions using the settings **G From the **Pull Requests** view you can view, manage, and create pull requests. -![Pull Request View](images/github/pull-request-view.png) +![Screenshot showing the Pull Request view.](images/github/pull-request-view.png) The queries used to display pull requests can be configured with the **GitHub Pull Requests: Queries** (`setting(githubPullRequests.queries)`) setting and use the [GitHub search syntax](https://docs.github.com/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). @@ -119,13 +127,13 @@ The queries used to display pull requests can be configured with the **GitHub Pu Once you have committed changes to your fork or branch, you can use the **GitHub Pull Requests: Create Pull Request** command or the **Create Pull Request** button in the **Pull Requests** view to create a pull request. -![Create Pull Request button in the Pull Request view](images/github/create-pull-request-button.png) +![Screenshot showing the Create Pull Request button in the Pull Request view.](images/github/create-pull-request-button.png) A new **Create** view will be displayed where you can select the base repository and base branch you'd like your pull request to target as well as fill in the title and description. If your repository has a pull request template, this will automatically be used for the description. Use the buttons in the action bar at the top to add **Assignees**, **Reviewers**, **Labels** and a **Milestone**. -![Create Pull Request view](images/github/create-pull-request-view.png) +![Screenshot showing the Create Pull Request view.](images/github/create-pull-request-view.png) The **Create** button menu allows you to select alternative create options, such as **Create Draft** or enable an **Auto-Merge** method. diff --git a/docs/sourcecontrol/images/github/extension-signin.png b/docs/sourcecontrol/images/github/extension-signin.png index 14d9ec4b28..e55be88463 100644 --- a/docs/sourcecontrol/images/github/extension-signin.png +++ b/docs/sourcecontrol/images/github/extension-signin.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:777c2340b7184a7621793cb5a770431b62ea3a943765393039f8f4a521a62371 -size 37199 +oid sha256:01ba46509b3c446adc39b5a9325daa6f7d4cc497025d62fe3be1c754e3516087 +size 30641 From a4c185845dc05d344b58a5d875687238b9bc77bd Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Tue, 25 Nov 2025 11:08:17 +0100 Subject: [PATCH 11/12] Edit pass --- .../images/overview/git-blame-status-bar.png | 3 +++ docs/sourcecontrol/overview.md | 26 +++++++++---------- 2 files changed, 15 insertions(+), 14 deletions(-) create mode 100644 docs/sourcecontrol/images/overview/git-blame-status-bar.png diff --git a/docs/sourcecontrol/images/overview/git-blame-status-bar.png b/docs/sourcecontrol/images/overview/git-blame-status-bar.png new file mode 100644 index 0000000000..d615d723b6 --- /dev/null +++ b/docs/sourcecontrol/images/overview/git-blame-status-bar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0bf59273c924f99d51c551efdae0280a5ca8a125e2e2d7191315ee93475daa1c +size 138441 diff --git a/docs/sourcecontrol/overview.md b/docs/sourcecontrol/overview.md index b5e1e3acd7..2cbe8b2a2c 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -67,9 +67,7 @@ VS Code provides Git functionality through several key interface elements. This * **Additional UI elements**: in-context Git information like editor gutter indicators or Git blame annotations - ![Screenshot of editor gutter indicators showing line changes and a hover showing Git blame information.](images/overview/gutter.png) - -If you prefer using the command line, you can still run Git commands in the integrated terminal (`kb(terminal.toggleTerminal)`). Changes made via the terminal are reflected in the VS Code source control interface. + ![Screenshot of editor gutter indicators showing line changes and a hover showing Git blame information.](images/overview/git-blame-status-bar.png) ## Common workflows @@ -109,21 +107,19 @@ When you encounter merge conflicts, VS Code highlights the conflicting files in ![Screenshot of the 3-way merge editor.](images/overview/merge-editor-overview.png) -Once resolved, you can stage the files and commit the merge. - Learn more about [resolving merge conflicts](/docs/sourcecontrol/merge-conflicts.md). ### Work with branches, worktrees, and stashes -VS Code supports multiple workflows for managing parallel development work. You can easily switch between branches within a single workspace. +VS Code supports multiple workflows for managing parallel development work. -![Screenshot of the branch Quick Pick showing options to switch to a branch or create a new branch.](images/overview/gitbranches.png) +* Quickly switch between **branches** within a single workspace to work on different features or fixes. -To work with multiple branches simultaneously, you can use Git worktrees to create separate working directories for different branches. + ![Screenshot of the branch Quick Pick showing options to switch to a branch or create a new branch.](images/overview/gitbranches.png) -![Screenshot of the worktrees submenu in the Source Control Repositories view.](images/overview/worktree-create.png) +* Use Git **worktrees** to create separate working directories for different branches to work with multiple branches simultaneously. -Temporarily save uncommitted changes when you need to switch contexts quickly by using a Git stash: save, view, apply, or pop your stashed changes directly from the Source Control view. +* Use Git **stashes** to temporarily save uncommitted changes when you need to switch contexts quickly. Learn more about [working with branches and worktrees](/docs/sourcecontrol/branches-worktrees.md). @@ -131,13 +127,15 @@ Learn more about [working with branches and worktrees](/docs/sourcecontrol/branc It can be helpful to review the commit history to understand how your code has changed over time. -The Source Control Graph provides a visual representation of your branch structure and commit history, highlighting incoming and outgoing commits. +* The **Source Control Graph** provides a visual representation of your branch structure and commit history, highlighting incoming and outgoing commits. + + ![Screenshot of the Source Control Graph showing commit history and branch structure.](images/overview/source-control-graph.png) -The Timeline view in the Explorer view shows the commit history for a specific file, allowing you to see how it has evolved. You can filter the timeline to show only Git commits or to also include local file changes. +* The **Timeline view** in the Explorer view shows the commit history for a specific file, allowing you to see how it has evolved. You can filter the timeline to show only Git commits or to also include local file changes. -![Screenshot of the timeline view showing file commit history.](images/overview/timeline-view.png) + ![Screenshot of the timeline view showing file commit history.](images/overview/timeline-view.png) -Learn more about [using the Timeline view and reviewing changes](/docs/sourcecontrol/staging-commits.md#timeline-view-for-file-history). +Learn more about [using the Graph and Timeline view and reviewing changes](/docs/sourcecontrol/staging-commits.md#timeline-view-for-file-history). ## Working with GitHub pull requests and issues From aaae9a8c2b68488bebf6a58e9e479dc5a7c02b16 Mon Sep 17 00:00:00 2001 From: Nick Trogh Date: Wed, 26 Nov 2025 08:41:46 +0100 Subject: [PATCH 12/12] Add repos screenshot --- .../images/repos-remotes/multiple-repositories.png | 3 +++ docs/sourcecontrol/repos-remotes.md | 6 ++++++ 2 files changed, 9 insertions(+) create mode 100644 docs/sourcecontrol/images/repos-remotes/multiple-repositories.png diff --git a/docs/sourcecontrol/images/repos-remotes/multiple-repositories.png b/docs/sourcecontrol/images/repos-remotes/multiple-repositories.png new file mode 100644 index 0000000000..db60b8a285 --- /dev/null +++ b/docs/sourcecontrol/images/repos-remotes/multiple-repositories.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3bf5e2346f4b83c4a08ac53b23d61f2e61b755512f6222bd172e3b54e1f4f000 +size 94278 diff --git a/docs/sourcecontrol/repos-remotes.md b/docs/sourcecontrol/repos-remotes.md index 2ffee785b0..4ec61395c2 100644 --- a/docs/sourcecontrol/repos-remotes.md +++ b/docs/sourcecontrol/repos-remotes.md @@ -225,12 +225,18 @@ Learn more about [viewing commit history with the Source Control Graph](/docs/so The Repositories view enables you to manage multiple Git repositories in a single workspace. This is useful when working with projects that span multiple repositories. +![Screenshot of the Repositories view in VS Code showing multiple Git repositories.](images/repos-remotes/multiple-repositories.png) + To show the Repositories view, run the **Source Control: Focus on Repositories View** command from the Command Palette (`kb(workbench.action.showCommands)`). Configure the `setting(scm.alwaysShowRepositories)` setting to always show the Repositories view in the Source Control view. +For each repository, you can see the active branch, sync status, and access actions like fetch, pull, push, and more. + VS Code automatically detects Git repositories when you open folders that contain them. If you open a folder with multiple repositories (like a monorepo), all repositories appear in the Repositories view. You can configure whether you want to have multiple repositories active in the Source Control view or a single repository at a time by changing the `setting(scm.repositories.selectionMode)` setting. +When operating in multi-repo mode, the Source Control view shows changes across all repositories. In single-repo mode, the view only shows changes for the selected repository in the Repositories view. + ## Credential helpers Credential helpers securely store your authentication credentials so you don't have to enter them every time you push or pull. You should [set up a credential helper](https://docs.github.com/get-started/getting-started-with-git/caching-your-github-credentials-in-git) to avoid getting asked for credentials every time VS Code interacts with a remote repository.