Lesson 2 of 8 in Git and collaboration

Staging and writing commits

Core9 minWritten for Git 2.28 or newer

The working tree is the folder you edit. The index, also called the staging area, is the list of changes you have chosen for the next commit. A commit saves exactly what is in the index, not everything you changed.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: How git stores history

The problem this solves

You often change several things in one sitting: a bug fix, a renamed variable, a half-finished experiment. If a commit had to include every edit, history would be one blob nobody can review or undo in parts.

The staging area lets you pick which changes belong together. One commit then says one thing, such as fix the timeout in the deploy script. When a deploy goes wrong a month later, a clean history lets you find the commit that did it and undo only that.

The same step is where mistakes slip in. Staging everything with git add . can sweep in logs, build output and files holding passwords. Knowing what is staged before you commit is the cheapest safety check in git.

How it works

Three places a change can live
Three places a change can liveYou edit files in the working tree, git add copies chosen changes into the staging area, and git commit saves the staged snapshot into the repository.0 edit1 git add2 git commitYouedit filesWorking treethe folder you seeStaging areathe next commit, draftedRepositorysaved commits
  • People and clients
  • Runs code
  • Control
  • Data

You edit files in the working tree, git add copies chosen changes into the staging area, and git commit saves the staged snapshot into the repository.

  1. You to Working tree: 0 edit
  2. Working tree to Staging area: 1 git add
  3. Staging area to Repository: 2 git commit

Follow the arrows left to right. You edit files, and they sit in the working tree as plain changes that git has noticed but not saved. git add copies the current content of a file into the staging area. git commit turns whatever is staged into a new commit.

A file can be in two states at once. If you stage a file and then edit it again, the staging area holds the older version and the working tree holds the newer one. The commit takes the staged version. This surprises almost everyone once.

git status compares the three places for you. git diff shows working tree against staging area, and git diff --staged shows staging area against the last commit. Reading both before you commit is the habit to build.

Try it yourself

Use a fresh throwaway folder. You will stage one file, edit it again, and see that the commit only contains what was staged.

  1. 1
    Set up and create two files
    mkdir git-lab-2 && cd git-lab-2
    git init -b main
    git config user.name "Your Name"
    git config user.email "you@example.com"
    echo "first line" > notes.txt
    echo "buy milk" > todo.txt
    git status -s

    You should see

    ?? notes.txt
    ?? todo.txt

    -s is the short format. ?? means git sees the file but does not track it yet.

  2. 2
    Stage only one file
    git add notes.txt
    git status -s

    You should see

    A  notes.txt
    ?? todo.txt

    A in the first column means the file is staged as a new file. todo.txt stays out of the next commit.

  3. 3
    Edit the staged file again
    echo "second line" >> notes.txt
    git status -s
    git diff
    git diff --staged

    You should see

    AM notes.txt
    ?? todo.txt

    AM means added to the index and modified again in the working tree. git diff shows only the second line. git diff --staged shows the file as it was when you staged it.

  4. 4
    Commit, then check what was saved
    git commit -m "Add notes file" -m "Starts the notes list. The todo file is kept out on purpose."
    git show --stat
    git status -s

    Two -m options give a subject line and a body. The commit contains only the first line of notes.txt. The status afterwards still lists the second-line edit and todo.txt.

  5. 5
    Stage the rest in pieces
    git add -p notes.txt

    -p walks through each changed chunk and asks whether to stage it. Answer y to stage a chunk, n to skip it, q to quit. This is how you split one messy session into clean commits.

What breaks, and where to look

  • Author identity unknown *** Please tell me who you are.

    WHY IT HAPPENS
    Git writes your name and email into every commit and has none configured on this machine or repository.
    CHECK FIRST
    Run git config user.name and git config user.email. Set them with git config --global user.name "Your Name" and the same for user.email, or leave out --global to set them for one repository.
  • You committed, but your last edit to a file is missing from the commit and git status shows the file as changed again.

    WHY IT HAPPENS
    You edited the file after git add. The commit saved the version that was staged at the time.
    CHECK FIRST
    Run git status -s. A second letter in the second column, as in AM or MM, means staged and then edited again. Run git add <file> again before committing.
  • nothing added to commit but untracked files present (use "git add" to track)

    WHY IT HAPPENS
    New files are not tracked until you stage them once. git commit -a only includes files git already knows.
    CHECK FIRST
    Run git status, find the files under Untracked, and stage them with git add <file>.

When not to use this

  • git add . and git commit -a are fast but stage everything, including files you did not mean to share. For anything touching credentials, run git status and git diff --staged first.
  • A good message cannot rescue a commit that mixes unrelated changes. Split the work with git add -p instead of explaining the mix in the message.

Check yourself

What does a commit save?

Exactly what is in the staging area at that moment, not everything you changed in the working tree.

How can a file show as both staged and modified?

You staged it, then edited it again. The staging area holds the old version and the working tree holds the new one.

Which command shows what the next commit will contain?

git diff --staged, which compares the staging area with the last commit.

Lesson 32 of 92 in the DevOps path

Search

Search cheat sheets and projects