Configure LinkORB's commit message template

An effective commit message summarizes changes introduced in a commit. It ensures collaborators understand a change and the motivation for that change without digging through every minute detail.

To ensure team members write effective commit messages, the LinkORB Engineering team maintains a commit template which provides hints in a commit message editor. The following guide outlines how to configure and use LinkORB’s commit template when contributing to a Git repository.

Add a commit message template to a containerized repository

Configure a commit template for a repository that implements containerization through a devcontainer.json file and/or a Dockerfile by adding the master copy of LinkORB’s commit template to the build using wget or curl as follows:

RUN wget https://raw.githubusercontent.com/linkorb/.github/master/linkorb_commit.template && \
  git config --global commit.template linkorb_commit.template

Configure an existing commit message template for a non-containerized repository

If a linkorb_commit.template file already exists at the root of a repository, you can configure Git to use the existing template as follows:

Open a terminal and navigate to the repository. If you’re using VSCode, press Ctrl + ` to use the integrated terminal.
Configure Git to use the commit template by running the following command.

git config --local commit.template linkorb_commit.template

git commit --amend is useful for modifying your last commit message. However, Git will not use the commit template for git commit --amend operations. You may need to rely your commit message’s editor’s rulers instead. See configure commit message rulers for more information.

Git will use the set commit message template the next time you run git commit from the command line or from the IDE’s source control tool.

When using VSCode, you can also initiate the template after staging changes by clicking the Commit button (without filling out the message field) or by pressing Ctrl + Enter when the message field has focus.

The commit template configuration above does not apply to git commit operations run with the -m option (i.e. git commit -m "commit message example") or messages typed directly into the message field in VSCode’s source control pane.

Create and configure a commit message template for a non-containerized repository

Check the root of the repository for a linkorb_commit.template file. If the file does not exist, create and configure it as follows:

Create the linkorb_commit.template file and save it to the root of the repository.
Copy the following template into the just created linkorb_commit.template file:

# See https://engineering.linkorb.com/topics/github-codespaces/articles/commit-standards for more information
#
# Write a 50-character or less commit header below
# It should take the form: <type>[scope]: <description> #<cardNumber>
# -----------------------50 characters ends here:#


# [optional body]
# Summarize changes and the motivation for such changes below:
# Keep lines short (72 characters or less) ----72 characters ends here:#


# [optional footer]
# Summarize supplemental information such as breaking changes, work item identifiers, co-authors, etc
# Keep lines short (72 characters or less) ----72 characters ends here:#

Press Ctrl + S to save the template.
Complete the steps in Configure existing commit message template.

Configure commit message editor rulers

Setting up vertical rulers in your chosen commit message editor helps you adhere to the 50- and 72-character guidelines for a commit message’s header and body respectively.

Configure commit message rulers in VSCode

To use vertical rulers to commit messages when using VSCode, first check if the JSON object in the repository’s .vscode/settings.json file has the following entry:

"[git-commit]": {
  "editor.rulers": [50, 72]
  }

If the .vscode/settings.json file already has the above entry, the ruler should work by default. If the .vscode/settings.json file exists but does not have the git-commit entry above, copy the above entry into the JSON object. If the .vscode/settings.json file does not exist, add one to the repository as follows:

Press Ctrl + Shift + P to open the command palette
Type settings.json into the search field and select Preferences: Open workspace settings (JSON)

Copy the following code block into the file and save it.

{
  "[git-commit]": {
    "editor.rulers": [50, 72]
    }
}

For reference, the commit message template may look as follows:

commit message template

:::warningThe above rulers only work if VSCode is set as Git’s commit message editor. Run git config --global core.editor code to set VSCode as your commit message editor. If you decide to use a different editor (vim, nano etc.), please add vertical rulers to it, or use the lines highlighted below for (character count) reference. :::

commit template in other editor

Configure commit a message ruler in nano

Run the following command to set a 50-character vertical ruler before using nano as your commit message editor.

echo 'set guidestripe 50 # Set a vertical ruler at column 50' >> ~/.nanorc

Configure commit message rulers in vim

Run the following command in the terminal to set 50- and 72-character rulers before using vim as your commit message editor.

Simply append 50,72 to the value(s) of vim’s colorcolumn setting if you have previously configured a vertical ruler.

echo 'set colorcolumn=50,72 " Set vertical rulers at columns 50 and 72' >> ~/.vimrc

Configure LinkORB's commit message template in [#git]