Alex headshot

AlBlue’s Blog

Macs, Modularity and More

Git Tip of the Week: Adding content

2011, git, gtotw

As the second of a new series of Git Tips, I'm posting a git tip per week. If you don't subscribe to my blog then these are available as a separate feed which you can subscribe to.

Identify yourself

The first thing you need to do is tell Git who you are, so that any subsequent commits record your authorship appropriately. It is possible to do this on a repository-by-repository basis, but it's usually the case you configure this on a global level. (To configure on a per-project level, run inside a repository and without the --global flag.)

$ git config --global user.name Alex Blewitt
$ git config --global user.email alex.blewitt@gmail.com

Note that the email is case sensitive, and some systems will be picky about matching the case exactly. If you set this up at the global level,then you don't need to do this step again.

Adding content

Adding content to a Git repository is done in two stages; firstly, adding the content itself, and secondly, committing the changeset.

Like other version control systems, you need to add content to a repository to tell it what is under the repository's control. To do this with Git, you use git add to add one or more files under Git's control:

$ git add file.c file.h docs/

Once files have been added, the changeset can be committed into the repository with git commit:

$ git commit

When a set of changes are committed, you have the opportunity to add comments describing the changeset. Unlike CVCS, the commit message is per changeset commit, rather than per file. If you don't specify it on the command line (with the -m flag) then you'll be put into your editor.

The standard format of a commit message is described in git-commit: conventionally, the first line contains a present tense description of the change, followed by a blank line, followed by more descriptive changes if needed. Conventionally, the last paragraph consists of Key: Value pairs which can be used to record arbitrary information, such as which issue they are associated with, who signed the change off etc. A commit message may look like:

Handle legacy encodings

By default we expect UTF-8; however,
we should handle cases where it is not.

Bug: 123
Signed-off-by: Alex Blewitt <Alex.Blewitt@gmail.com>
Change-Id: Ia2dd79e7d8fd33e9940f7eb9cf68ece2cfcf9e2c 

The soft limit of 50 characters for the first line is not enforced, but since some commands show just the first line (in particular, git log --oneline) then it makes sense to keep to that level. As with other version control systems, the commit message should explain the intent behind the changeset, not the implementation details behind the change (since that can be derived from the diff anyway).

Adding subsequent changes

One difference from Git is subsequent changes to the files also need a git add. Git has a concept called the index, which we'll cover in a future tip. When you do an add, you're not just adding the file to the repository, but you're adding a specific version of the file to the repository.

To get stated with Git, you can default to using git commit -a. This has the same effect as adding all previously added files, which may be what you expect initially. Running git status will tell you what's outstanding.


Come back next week for another instalment in the Git Tip of the Week series