diff --git a/build/sitemap.xml b/build/sitemap.xml index 1abd6c7d76..e05218f805 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -290,11 +290,26 @@ weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/quickstart + weekly + 0.8 + https://code.visualstudio.com/docs/sourcecontrol/intro-to-git weekly 0.8 + + https://code.visualstudio.com/docs/sourcecontrol/staging-commits + 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/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/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/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/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 cc2d7d0b9d..96ee8391a0 100644 --- a/docs/sourcecontrol/overview.md +++ b/docs/sourcecontrol/overview.md @@ -1,432 +1,160 @@ --- 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. - - - -> [!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 +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. -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. +## Prerequisites -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. +To use Git features in VS Code, you need: -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. +* VS Code uses your machine's Git installation. [Install Git version 2.0.0 or later](https://git-scm.com/download) on your machine. -![Overview of Git](images/overview/overview.png) +* When you commit changes, Git uses your configured username and email. You can set these values with: -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. + ```bash + git config --global user.name "Your Name" + git config --global user.email "your.email@example.com" + ``` > [!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) - -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. - -For a GitHub repository, you would find the URL from the GitHub **Code** dialog. - -![clone repository dialog](images/overview/GitHub-clone-dialog.png) - -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. +> 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). -> [!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. +## Get started with a repository -## Initialize a repository +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: -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**. +* **Initialize a new repository**: Create a new Git repository for your current folder. -![Git initialize repository](images/overview/initialize-repository.png) +* **Clone a repository**: Clone an existing repository from GitHub or another Git host. -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) +* **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] -> 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)`). - - - -### Generate a commit message with AI - -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. - -![Screenshot that shows the Generate Commit Message with Copilot button in the commit message input box.](images/overview/copilot-generate-commit-message.png) - -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). - -### 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. +> 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. -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. +Learn more about [cloning and publishing repositories](/docs/sourcecontrol/repos-remotes.md#clone-repositories). -![Author commit message in a full text editor](images/overview/scm-git-editor.gif) +## Source control interface -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. +VS Code provides Git functionality through several key interface elements. This UI integration enables you to perform Git operations without knowing terminal commands: -To use the same flow for git commit commands executed in the integrated terminal, enable the `setting(git.terminalGitEditor)` setting. +* **Source Control view**: central hub for common Git operations like staging, committing, and managing changes -## Git blame information + ![Screenshot of the Source Control view showing staged changes, and the diff editor showing side-by-side changes.](images/overview/overview.png) -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. +* **Source Control Graph**: graphical representation of your commit history and branch relationships -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: + ![Screenshot of the Source control graph showing commit history.](images/overview/source-control-graph.png) -- `setting(git.blame.statusBarItem.enabled)` (enabled by default) -- `setting(git.blame.editorDecoration.enabled)` +* **Diff editor**: side-by-side file comparisons for effective change review - + ![Screenshot of the diff editor showing changes between file versions.](images/overview/diff.png) -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. +* **Additional UI elements**: in-context Git information like editor gutter indicators or Git blame annotations -For example, the following template shows the subject of the commit, the author's name, and the author's date relative to now: + ![Screenshot of editor gutter indicators showing line changes and a hover showing Git blame information.](images/overview/gutter.png) -```json -{ - "git.blame.editorDecoration.template": "${subject}, ${authorName} (${authorDateAgo})" -} -``` +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. -To adjust the color of the editor decoration, use the `git.blame.editorDecorationForeground` theme color. +## Common workflows -## Review uncommitted code changes with AI +### Review changes before committing -GitHub Copilot in VS Code can help you review your uncommitted code changes. +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. -1. In the Source Control view, select the **Code Review** button to start a code review of the uncommitted changes +![Screenshot of the code review results, showing as editor overlay comments.](images/overview/copilot-code-review-results.png) - ![Screenshot that shows the Code Review button in the Source Control view.](images/overview/copilot-code-review.png) +### Stage and commit changes -1. Copilot generates code review comments and suggestions as overlays in the editor +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. - ![Screenshot that shows the code review comments generated by Copilot.](images/overview/copilot-code-review-results.png) +![Screenshot of staging changes in the Source Control view.](images/overview/stage-changes.png) - You can also view a list of all code review comments in the **Comments** panel. +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. -1. You apply or discard suggestions by using the corresponding buttons, or context menu actions in the Comments panel +![Screenshot of generating a commit message with Copilot.](images/overview/copilot-generate-commit-message.png) -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. +Learn more about [staging changes and writing commits](/docs/sourcecontrol/staging-commits.md). -## Branches and Tags +### Sync with remotes - +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. -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)`). +![Screenshot of the Source Control view showing the sync button indicating outgoing and incoming changes.](images/overview/incoming-outgoing-changes.png) -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. +Learn more about [working with repositories and remotes](/docs/sourcecontrol/repos-remotes.md). -![Git checkout](images/overview/gitbranches.png) +### Resolve merge conflicts -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. +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: -> [!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 - -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. - -> [!NOTE] -> You can disable automatic worktree detection by toggling the `setting(git.detectWorktrees)` setting. - -### Create a worktree - -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)`). - -1. In the Source Control view, select **...** > **Repositories** to open the Source Control Repositories view. - - ![Screenshot that shows the Repositories option in the Source Control view.](images/overview/source-control-view-repositories.png) - -1. Right-click on a repository, and select **Worktrees** > **Create Worktree...** - - ![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) - -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 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. - -### 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. - -### Manage worktrees - -All detected worktrees are shown in the Source Control Repositories view, grouped under their parent repository. - -When you select a worktree in the list, the Changes view shows the pending changes for that worktree. - -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. - -### 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 that shows the Compare with Workspace option in the context menu of a changed file in a worktree.](images/overview/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. - -## 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) +Learn more about [using the Timeline view and reviewing changes](/docs/sourcecontrol/staging-commits.md#timeline-view-for-file-history). -## Gutter indicators +## Working with GitHub pull requests and issues -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. +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: -* A red triangle indicates where lines have been deleted -* A green bar indicates new added lines -* A blue bar indicates modified lines +* 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 -![Gutter indicators](images/overview/gutter.png) +Learn more about [working with GitHub in VS Code](/docs/sourcecontrol/github.md). -## Merge conflicts +## Other source control providers -![Git merge](images/overview/merge-conflict.png) +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. -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. +* [Source Control Quickstart](/docs/sourcecontrol/quickstart.md) - Quickly get started with Git source control in VS Code -* Learn more about [Copilot VS Code](/docs/copilot/overview.md) - Learn about Copilot in VS Code. +* [Intro Video - Git Version Control](/docs/introvideos/versioncontrol.md) - An introductory video providing an overview of VS Code Git support -* [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. +* [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 new file mode 100644 index 0000000000..a48b2a5dee --- /dev/null +++ b/docs/sourcecontrol/quickstart.md @@ -0,0 +1,150 @@ +--- +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 affected 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: + +* [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 new file mode 100644 index 0000000000..08688a3e3a --- /dev/null +++ b/docs/sourcecontrol/staging-commits.md @@ -0,0 +1,240 @@ +--- +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. +--- +# Staging and committing changes + +Creating focused commits with clear descriptions helps you and your team understand the history of your codebase. VS Code provides integrated Git tools for staging changes and creating commits, with support for granular control over which changes to include. + +This article covers the staging and commit workflow in VS Code, from Git's two-step process to using AI assistance for commit messages and reviewing changes before committing. + +## Git workflow + +Git uses a two-step process to save your work: staging and committing. When you modify files, Git tracks these changes but doesn't automatically include them in your next commit. Staging lets you select which changes to include in each commit. + +Think of staging as preparing a snapshot of your work. You can stage all changes at once for a comprehensive commit, or stage specific files and even individual lines to create focused, logical commits that are easier to review and understand later. + +## View changes + +The Source Control view (`kb(workbench.view.scm)`) is your central hub for managing changes in your Git repository. Changes are organized into two sections based on their staging status: + +* **Changes**: lists all modified, added, or deleted files that are not yet staged for commit +* **Staged Changes**: lists files that have been staged and are ready to be committed + +![Screenshot of the Source Control view showing a modified and new file under Changes.](images/staging-commits/view-changes.png) + +Notice that changed files are listed with a "U" (untracked), "M" (modified), or "D" (deleted) icon next to them to indicate the type of change. This change indicator is also shown in the Explorer view and in the editor tab title for modified files. + +The source control icon in the Activity Bar also shows a badge with the number of affected files to give you a quick overview of your uncommitted changes. + +> [!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 + +* [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 cca368e675..a4adc92f8e 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -170,7 +170,10 @@ "area": "sourcecontrol", "topics": [ ["Overview", "/docs/sourcecontrol/overview"], + ["Quickstart", "/docs/sourcecontrol/quickstart"], ["Introduction to Git", "/docs/sourcecontrol/intro-to-git"], + ["Staging & Committing", "/docs/sourcecontrol/staging-commits"], + ["Repositories & Remotes", "/docs/sourcecontrol/repos-remotes"], ["Collaborate on GitHub", "/docs/sourcecontrol/github"], ["FAQ", "/docs/sourcecontrol/faq"] ] @@ -362,7 +365,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"] ] }, {