Commits – best practices

Like everything else in programming, best practices in commits are, to some degree, controversial. The first issue is frequency.

How often should I commit?

There are those who say a commit should be atomic: representing exactly one unit of work (one task, one bug fix). No more and no less. So, according to this line of thought, if you are in the middle of work and you get called away, you should not commit, but you should use the stash. The stash is an area where you can put files that you want to come back to later. You can name sets of files that you stash, and then pick the one you want to restore by name.

This is a defensible position, but I hold the opposite: commit early and commit often.

Commits are cheap and fast in Git, and interactive rebase (see Chapter 6, Interactive Rebasing) allows you to "squash" commits together. Therefore, if you are working on a feature and you make five interim commits before you are done, you'll have the opportunity to squash them into a single commit with a single message. This is the best of both worlds: you secure your interim work with a commit, and you present only one commit (rather than five) to the server.

Keep your commit history clean

The first way that a programmer reviews your code is to look at the list of commits and then dive into those that are interesting. A good history of commits with well-written messages is a delight to review. A long, tedious history with meaningless messages is only slightly more fun than eating glass.

A note on commit messages

As you will see later in this book, commit messages are very important for anyone (including you) reviewing your commit history. By convention, commit messages should be in the imperative, and should tell you exactly what is in that commit.

Fixing some files                        // bad
Fix WriteLine in helloworld.cs           // good

In practice you'll often find comments in the past tense:

Fixed WriteLine in helloworld.cs         // good enough

"In theory, theory and practice are the same; in practice, they never are." -- Pat Johnson

It pays to get into the habit of writing good messages in the right format. Your teammates will thank you.

When the title isn't enough

The message title should be kept to 50 characters. Most of the time this is enough, but if it isn't, leave the -m message off and let Git open your editor. There you can add additional information. Skip a line after the header and consider using bullet points or other ways of making the things you want to convey easy to read.

Important: By default Git uses vi (a Unix editor). You'll want to enter:

git config ––global core editor "code -w"

This ensures that Visual Studio Code is your default editor:

Figure 2.22: Editing in Visual Studio Code

Note that # is the comment character, and all lines that begin with # will be ignored.

When you use log (see Chapter 9, Using the Log) to see your history (or view history in Visual Studio, etc.) you'll see the entire message:

Figure 2.23: The output of the log command

You can see just the headers if you want, using git log -–oneline, but we'll leave the details for Chapter 9, Using the Log:

Figure 2.24: log using the oneline flag