Committing

Exercise 02 Committing

Now that you know how to arrange your staging area, it’s time to commit.

docker run -it gitforpragmatists/01-basics-02-committing

What is a commit?

For our purposes¹ a commit is a set of changes git can apply to get from a known point (the previous commit) to the desired state and a message to explain to humans what the effect of the changes is.

This is useful to us because we can later get back to the state we were in at a given commit, review the history of a file to learn what changes were made to it and why and restore parts of our files to how they were previously if we decide we don’t like a particular change after all.

git commit

A quick git status and git diff --cached will show us what we’ve got staged

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   NewFile.md
        modified:   README.md

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:   NewFile.md
        modified:   README.md

$ git diff --cached
diff --git a/NewFile.md b/NewFile.md
new file mode 100644
index 0000000..061ad98
--- /dev/null
+++ b/NewFile.md
@@ -0,0 +1 @@
+I'm a completely new file which has been staged.
diff --git a/README.md b/README.md
index 1ca8e2e..37816fb 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,3 @@
 Welcome to exercise 02, committing!
+
+I'm a staged change.

I like these changes and I’m happy to commit them.

$ git commit -m "Update documents to demonstrate commit"
[main 5903a2b] Update documents to demonstrate commit
 2 files changed, 3 insertions(+)
 create mode 100644 NewFile.md

I invoked git commit with -m in order to provide the commit message on the command line. You can provide -m multiple times to get a commit message with a subject and a multi-line body.

git commit -m "Add feature" -m "Feature is being added for this reason." -m "More information useful to the reader"

If you omit the -m argument git will open your configured text editor to allow you to write a more expansive message. By default in the exercise images your editor is configured to be nano. If you would rather use vim you can set it like so:

export EDITOR=vim

git commit

Amending

If you discover that your most recent commit is missing a change you would have liked to include or you want to alter the commit message you can combine the current staging area with your most recent commit.

Using git log we can see the commits starting with the most recent commit and working backwards in time.

$ git log
commit 5903a2b4063f13f60adee9355d546abecd38700c (HEAD -> main)
Author: Git Student <test@example.com>
Date:   Sat Aug 13 11:12:46 2022 +0000

    Update documents to demonstrate commit

commit e7ed9046705e7534a3b398814eddea3dbde4a784
Author: Elliot <elliot@gitforpragmatists.xyz>
Date:   Fri Aug 12 20:39:57 2022 +0000

    Add basic cake recipe
...

$ git commit --amend -m "Update README to demonstrate commit" -m "Add a new file"
[main 6e9d34f] Update README to demonstrate commit
 Date: Sat Aug 13 11:12:46 2022 +0000
 2 files changed, 7 insertions(+)
 create mode 100644 NewFile.md

$ git log
commit 6e9d34f1dd9309015d28953202e844fa0a49406e (HEAD -> main)
Author: Git Student <test@example.com>
Date:   Sat Aug 13 11:12:46 2022 +0000

    Update README to demonstrate commit

    Add a new file

commit e7ed9046705e7534a3b398814eddea3dbde4a784
Author: Elliot <elliot@gitforpragmatists.xyz>
Date:   Fri Aug 12 20:39:57 2022 +0000

    Add basic cake recipe
...

If you’ve added any changes to the staging area they will also be folded into the amended commit. If you’re happy with the commit message as is you can pass --amend --no-edit

$ git add README.md
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   README.md

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:   NewFile.md

$ git commit --amend --no-edit
[main f742b97] Update README to demonstrate commit
 Date: Sat Aug 13 13:08:08 2022 +0000
 2 files changed, 5 insertions(+)
 create mode 100644 NewFile.md

$ git log
commit f742b979094e32aaa0aba2483102187bdc7a143b (HEAD -> main)
Author: Git Student <test@example.com>
Date:   Sat Aug 13 13:08:08 2022 +0000

    Update README to demonstrate commit

    Add a new file

commit e7ed9046705e7534a3b398814eddea3dbde4a784
Author: Elliot <elliot@gitforpragmatists.xyz>
Date:   Fri Aug 12 20:39:57 2022 +0000

    Add basic cake recipe
...

Commit Messages

Some advice and personal preferences on commit messages.

Wherever you can do your best to describe the “Why?” as well as the “What?”. Commit messages are a great way to figure out what the motivation for a change was.

In general commit message style is a matter of personal preference. In some projects the style of commit messages is tightly prescribed. You should check with the maintainers of the project you’re working on if there is a specific style of commit message they use since the contents of the message is sometimes used for things other than git (e.g. software release notes).

In the absence of any prescribed style I like to use commit.style as a guide. It has the benefits of closely matching the commit messages that git itself will use when creating automatic commits and being very readable.