git commit: record a snapshot

git commit saves whatever sits in the index as a separate snapshot: with an author, a time, your message, and a unique hash.

A commit is not "save the file". It is the state of the whole project at one moment, a point in the history you can come back to a year later.

$ git commit -m "recipe: first version"
[main (root-commit) 3d0ab22] recipe: first version
 1 file changed, 2 insertions(+)
 create mode 100644 recipe.txt

Take the output apart. main is the branch you are standing on. root-commit shows up only on the very first commit of a repository, the one with no parent. 3d0ab22 is the short hash, the identifier of the snapshot you use to come back to this state. Then your message and the statistics: one file, two lines added. The last line says the file is new to the history.

The -m flag gives the message on the command line. Without it git opens the editor from the core.editor setting (see git config). Leave the editor without writing anything and no commit is made:

Aborting commit due to empty commit message.

What goes into a commit

Only the content of the index, that is, what you picked with git add. Edits made after that add stay outside. Untracked files and files listed in .gitignore never enter the snapshot at all.

Check the list before saving with git status: the Changes to be committed section is your future commit.

The -a flag: a shortcut

git commit -a stages every modified file git already tracks and commits them in one step. People usually glue it to -m:

$ git commit -am "recipe: sugar"
[main 2386e74] recipe: sugar
 1 file changed, 2 insertions(+)

-a does not pick up new files: they are untracked, and git knows nothing about them yet. After such a command git status still shows them where they were:

$ git status -s
?? draft.txt

Handy when you are editing two or three familiar files. Bad when there are many changes about different things: they all land in one snapshot.

Common mistakes

Messages like "edits" and "fix" mean nothing six months later. Write for your future self: what you did and why.

If there is nothing to commit, git says so and creates no snapshot:

$ git commit -m "nothing to save"
On branch main
nothing added to commit but untracked files present (use "git add" to track)

A typo in the message of the last commit is fixed by git commit --amend, as long as the commit has not gone to the server yet.

Where this is in the book

The topic is covered in Chapter 3. Three areas and your first commit.

To practise it by hand, take the interactive lesson Three areas and a commit.