What are staging areas?

When you run git status after modifying some files, you’ll see something like this:

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file1.txt
	modified:   file8.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file2.txt
	modified:   file4.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	file5.txt
	sacred-texts.txt

Notice there are three categories of files here: to be committed (also called staged), not staged for commit, and untracked files.

These are the different staging areas.

  • To be committed/staged means that these files will be included in the next commit made.
  • Not staged for commit means that git noticed changes in those files, but they will not be included by default next time git commit is run.
  • Untracked means that git is not watching those files.

Moving files between staging areas

There are two git subcommands we need to understand for this: git add and git resore.

git add

We introduced git add in the last tutorial. It moves a file to the staged area so that it will be included in the next commit. Here’s an example (the lines starting with $ are the commands run:

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file1.txt
	modified:   file8.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file2.txt
	modified:   file4.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	file5.txt
	sacred-texts.txt

$ git add file2.txt file5.txt

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file1.txt
	modified:   file2.txt
	modified:   file5.txt
	modified:   file8.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file4.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	sacred-texts.txt

As you can see, running git add file{2,5}.txt moved them to the staged area. This is also referred to as “staging” a file.

A file can also be partially staged, where some part(s) of it are included in the next commit, but not the whole thing. This usually happens when you stage a file and then edit it. Running git add <partially staged file> will stage the entire thing.

git restore

This command is slightly more complicated than the other ones we’ve used so far. git restore overwrites a file, using either the latest commit or the staged version as reference. That might be quite confusing at first, and that’s okay. You can always come back to a tutorial, man page, or documentation later.

git restore can be very dangerous since it won’t warn you before overwriting files. Be careful!

There are some options that control how the file is overwritten.

default (–worktree, -W)

By default if no options are specified, or with the --worktree, -W option, git restore will discard any unstaged changes. This means that if you have a partially staged file, the staged changes will be kept, while the unstaged ones will be discarded.

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file2.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified: file2.txt

$ git restore file2.txt

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file2.txt

Running git restore file2.txt discarded the unstaged changes in file2.txt while keeping the staged ones.

–staged, -S

Running git restore with the --staged, -S option will essentially unstage any currently staged changes, but does not discard them.

Example:

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file1.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified: file2.txt

$ git restore --staged file1.txt

$ git status

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified: file1.txt
	modified: file2.txt

Note that this command is also listed in the output of git status, so it’s easy to remember.

–worktree, -W and –staged, -S

Using both the --worktree, -W and --staged, -S options will completely overwrite the file to its last committed state. It discards both staged and unstaged changes.

$ git status

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   file1.txt

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file1.txt
	modified:   file2.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	file5.txt

$ git restore --worktree --staged file1.txt

$ git status

On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   file2.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	file5.txt

Running git restore --worktree --staged file1.txt discarded all changes in file1.txt.

Tip: using short options can make the commands much simpler. git restore -WS <file> is equivalent to the above command.

Tip: almost all git commands can handle directories, too. Since git doesn’t track directories, it just applies the command recursively to all files in the directory. So git add . will stage all files in the repo, and git restore --staged . will unstage them all.


Back to series