Git Course 0%

The Source Control view

Beginner VS Code UI ≈ 9 min

Before this lesson

What you will learn

  • What each section, mark and button does
  • Which button maps to which Git command
  • Where the graph, the timeline and the stash live

After this lesson you can

  • I can read the Source Control view the way I read git status

Why this matters

This one panel replaces git status, git diff, git add, git commit, git pull and git push. Reading it accurately is most of what makes the editor usable for Git, and it takes about ten minutes to learn.

The panel

The VS Code Source Control view, labelled A schematic of the Source Control view. At the top is the commit message box with a Commit button beside it. Below are two sections: Staged Changes, listing one file marked M with a minus button to unstage it, and Changes, listing two files, one marked M for modified and one marked U for untracked, each with a plus button to stage it and a curved arrow to discard it. Callouts explain that the plus stages a file, the minus unstages it, the curved arrow discards the edit permanently, and clicking a file name opens the diff rather than the file. Below the lists, the Sync Changes button shows incoming and outgoing counts. At the bottom, the Status Bar shows the branch name, which opens a menu to switch or create a branch. SOURCE CONTROL … Message (press ⌘Enter to commit) Commit Staged Changes 1 docs/getting-started.md − M Changes 2 docs/faq.md ↺ + M notes.txt + U ↻ Sync Changes 1↓ 2↑ ⑂ docs/12-windows-install-steps ↻ 1↓ 2↑ Commit box the message, then Commit; only staged changes go in − unstage = git restore --staged + stage · ↺ discard = git add · git restore discard cannot be undone M modified · U untracked click the name to open the diff, not the file Sync Changes = git pull, then git push Status Bar branch
The Source Control view: the commit box, Staged Changes, Changes, the file marks, and Sync Changes. Every control maps to a command.

Open it with the Source Control icon in the Activity Bar, or ⌃⇧G (Ctrl+Shift+G on Windows and Linux).

The sections

Section Contains In Git terms
Staged Changes What the next commit will include The staging area (lesson 2.2)
Changes Modified and untracked files not staged yet The working tree
Merge Changes Files with conflicts, during a merge Unmerged paths (lesson 15.7)

The split between the first two is the whole point of the panel. If it looks like unnecessary bureaucracy, lesson 5.3 is the argument for it.

The marks

A single letter after each file name, which is git status's letter:

Mark Means
M Modified
U Untracked, a file Git has never seen
A Added: staged for the first time
D Deleted
R Renamed
C Conflict

The buttons

Hovering a file shows up to three:

Button Does Command
+ Stage this file git add <file>
↺ Discard changes git restore <file> — permanent
− Unstage (on a staged file) git restore --staged <file>

The header of each section has the same buttons for everything in it. The discard button is the one to be careful with: it destroys work Git never recorded, and it is next to the stage button (lesson 12.9). VS Code asks for confirmation, and the confirmation is worth reading.

Above the lists sit the message box and Commit, and below them Sync Changes, which is git pull followed by git push. Its label carries the counts: 1↓ 2↑ means one commit to pull and two to push.

Clicking a file opens the diff

This surprises people: clicking a file name in Source Control opens a side-by-side comparison, not the file. The left side is the previous version, the right is yours, and the right side is editable, so you can fix something while reviewing it.

To open the file itself instead, click it in the Explorer, or use the Open File button on the diff.

The rest of the panel

Feature Where Does
Source Control Graph Below the file lists The commit history as a graph, with branches
Timeline In the Explorer, below the file tree One file's history, plus VS Code's own local saves
Stashes The … menu → Stash git stash and friends (command page)
Views and More Actions (…) Top right of the panel Everything without a button: pull, push, fetch, checkout, tags, remotes

The Timeline deserves a mention as a safety net: it records file saves independently of Git, so it can sometimes recover an edit you discarded before committing, which Git cannot (lesson 12.1).

How to do it

The panel, as commands:

Terminal
$ git status              # the two sections
$ git diff <file>         # what clicking a file shows
$ git add <file>          # +
$ git restore <file>      # ↺
$ git restore --staged <file>  # −
$ git commit -m "…"       # the message box and Commit
$ git pull && git push    # Sync Changes

Common mistakes

  • Clicking ↺ instead of +. Discard is permanent; read the confirmation.
  • Committing with nothing staged, which with smart commit on commits everything (lesson 15.1).
  • Expecting a file name to open the file. It opens the diff.
  • Ignoring the Sync counts, then being surprised by a rejected push.
  • Looking for pull and push as buttons. They are in the … menu, or use Sync.

Try it yourself

Goal: read the panel as fluently as git status.

  1. In your practice project, modify two files and create a third new file.
  2. Open the Source Control view and identify each mark: two M and one U.
  3. Stage one file with +, and watch it move to Staged Changes.
  4. Click each file name and read the diff; note that the right-hand side is editable.
  5. Commit only the staged file, then run git log --oneline -1 and git status in the integrated terminal to confirm the panel and the commands agree.

Expected result: one commit containing one file, with the other two still waiting, and the terminal confirming exactly what the panel showed.

Show solution

Step 5 is the point of the exercise. The panel is a view of the same repository the commands read, so the two can never disagree. Checking once builds the confidence to use whichever is faster in the moment.

Check yourself

1. What happens when you click a file name in the Source Control view?
2. Which button corresponds to git restore --staged <file>?
3. What does Sync Changes do?

Key terms

Staged Working tree Diff Commit

Related