Git guidelines

How we use Git, the distributed version control system (DVCS).

Commit messages

The seven rules of a great Git commit message

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why vs. how

Source: chris.beams.io/posts/git-commit/ (with more details)

Commit message subject

A properly formed Git commit subject line should always be able to complete the sentence "If applied, this commit will <subject>", doesn’t end with punctuation and the first letter is capitalized.

Commit message body

Reference tickets, issues, commits, tags, versions and pull requests where applicable. Our commit messages should look like this:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to at most 72
characters. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit's solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: CUST-123
See also: commit 00abc123, CUST-789

Account Usage and Commit Traceability

When working with VSHN or customer repositories on git.vshn.net, it’s important to ensure that all commits are associated with your official VSHN account. This practice enhances traceability and maintains professional standards, particularly when collaborating with customers.

Use Your VSHN Email

Always use your VSHN email account when making commits to VSHN or customer repositories. This ensures that all changes are correctly attributed to you within the organization.

Configure Your Git Email

Make sure to set your Git configuration to use your VSHN email address:

# set gobal config
git config --global user.email "your.name@vshn.net"
git config --global user.name "Your Name"
SSH Key Association

Ensure your SSH key is associated with your VSHN account to facilitate secure and traceable access to repositories.

Avoid Personal Accounts

Do not use personal GitHub accounts to commit to VSHN or customer repositories. Doing so can lead to confusion and concerns about the origin of the changes

# verify global config
git config --global --get-regexp "user"

# check if local repo config overrides global setting
git config --local --get-regexp "user"

Git Usage Basics

Example configuration

git config --global diff.color auto
git config --global color.interactive auto
git config --global color.status auto
git config --global color.ui auto
git config --global --bool merge.log 1
git config --global branch.autosetuprebase always
git config --global push.default tracking
git config --global format.thread shallow
git config --global --bool grep.lineNumber 1
git config --global --bool rebase.stat 1
git config --global --bool commit.verbose 1
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.st status
git config --global alias.cp cherry-pick
git config --global alias.wdiff 'diff --color-words'
git config --global alias.wshow 'show --color-words'

Example workflow

git clone git@git.vshn.net:vshn/handbook.git
git remote rename origin vshn

# add additional remote (optional) and pull in changes
git remote add github https://github.com/vshn/handbook.git
git pull github master
git push
# create a new branch for some changes
git checkout -b feature/add-git-guide-chapter
# (change or add some files)
git add -v .
git status
git commit -m 'Add new section'

# ooops, we made a mistake! Now update our last commit:
git commit -m 'Add new subsection' --amend
git push -u vshn feature/add-git-guide-chapter
# we added a new branch, let's double-check
git branch --remote

# after creating and merging a PR or MR, delete the branch
git checkout master
git pull
git branch -d feature/add-git-guide-chapter
git branch
git tag
git tag 1.0.0
git push --tags

Tools

CLI enhancements

TUI tools

Graphical tools