Page tree
Skip to end of metadata
Go to start of metadata

Hints, tips, conventions and dire warnings about working with Git in the Shibboleth project go here.

Note that these are all notes about working with Git in this specific project; Git has such a flexible array of composable tools that each project needs to establish its own conventions, and one project's workflow may not suit another project's requirements.

Files and Directories

Git does not track empty directories. If there's a reason you need the Git repository to contain a directory with no contents (one common case is a src/main/resources or src/test/resources expected by Eclipse) then the closest you can get is a directory with a hidden placeholder file. One common convention for this is to use an empty file called .gitkeep.

Tags

Lightweight tags created by git tag mytag are just synonyms for commits; they have no associated comment and no signature. You can use these freely in private repositories as bookmarks, creating, deleting or moving them as appropriate. You should never push lightweight tags to public repositories.

Any tag pushed to a public repository should have been created as an annotated (git tag -a) or signed (git tag -s) tag. These have an associated comment: this can be provided through the -m option; if you don't provide one, an editor will be started for you.

Most tags in our public repositories are used to label releases, and are given corresponding names without including a leading "v" or "V". For example: 1.2.11.3a2.7RC1.

Release tags should always include a comment of the form Tag version release and be signed using the releaser's GPG key using the -s option. For this to work, you will need to set your user-level ("global") configuration appropriately:

git config --global user.signingkey 0xkeyId


Then, sign as follows:

git tag -s -m "Tag 1.2.2 release" 1.2.2

You will be prompted for your GPG passphrase.

When you want to share a tag by pushing it to a public repository, push the single tag by name using git push remote tagname, for example git push origin 1.2.3

Although some online documents may suggest the use of git push --tags, you should never use this, as it pushes all tags in your repository.

Branches

Comments

In Git and many orther modern version control systems, comments on commits are by convention divided into two parts. Some tools assume this structure, so it's an important convention to stick to whenever you can.

The first line of a comment should be a summary. This should be short; limiting it to between 40 and 50 characters allows it to be properly displayed in things like short logs. If you want to include a JIRA case number, put that at the start of the line separated out by a " - " sequence, e.g.:

ABC-123 - fix typo in log message

If more detail is required in the comment than can be conveyed by the summary, it is followed by a blank line and any amount of detailed additional text. The blank line is important to some tools, so don't omit it. The additional text should be line-wrapped at something like 72 columns or thereabouts, as not all contexts in which it is displayed will wrap lines for you and overlong lines will make the comment hard to read.

Tim Pope's note about Git commit messages goes into more detail, and is well worth reading. A later summary of best practices is here.

Referring to the JIRA case using a URL sometimes makes sense if done in the additional text, not in the summary. Referring to other URLs can make sense too, as long as you're referencing something that won't move elsewhere in the lifetime of the codebase. For example, referring to another commit by referring to a web view URL is prone to failure in the longer term.

  • No labels