Git usage guidelines for team collaboration

By Alex3 minutes read

Introduction

This article outlines rules ideal for projects managed by small teams consisting of 3-8 members. These guidelines draw inspiration from conventional commits. Note that this discussion does not delve into GitFlow.

Branching model

  1. Always branch out from an updated “main” branch.
  2. Branches should be short-lived (maximum of 2 days) and focus on a specific goal.
  3. Once the goal is achieved, initiate a Pull Request (PR) to merge it with the main branch.
  4. After merging, promptly delete the branch.
  5. Only merge to the main branch, and ensure merges are squash merges for a tidy, brief history.

Branch names

While naming might seem trivial in tiny teams, it becomes essential for larger or remote teams. Consider the following naming convention:

<type>/[<ticket_id>]_<subject>

Applications like Sourcetree use the / to segment branch names in their interface, helping categorize branches.

Type

Ticket ID

If the branch’s objective is intricate or linked to a specific task, mention the corresponding ticket ID, e.g., PRJ_123.

Subject

Describe the branch’s specific purpose in 3-4 words. If there’s no ticket ID, the description’s precision becomes even more crucial.

Commit messages

Adopting a standardized commit message structure aids in automating change logs and semantic release updates using tools like semantic-release.

Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory, with the scope being optional. Ensure no line exceeds 100 characters for better readability across platforms.

Type

Use the previously mentioned types.

Scope

The scope provides context about the commit’s area of effect. It can be any noun pointing to a code section, or * for multiple areas.

Some teams leverage scope for ticket IDs, linking commits directly to tasks. This maintains ticket IDs in the history after squash merges.

Subject
  1. Adopt an imperative, present tense.
  2. Avoid capitalizing the first letter.
  3. Skip the period at the end.

Don’t use generic subjects as: ‘debug’ or ‘few fixes’. Be clear and specific.

Prioritize clarity. If you use automated changelog generators, ensure commit messages cater to all stakeholders.

Body

When used, the body should be in imperative, present tense and detail the motivation behind changes.

Reserved for details on breaking changes or referencing GitHub issues. Start with “BREAKING CHANGE:” followed by an explanation.

Pull requests (or merge requests)

Henceforth referred to as PRs, these are synonymous with merge requests.

For squash merges, the commit message format typically applies to the PR title and description. I prefer using the initial commit message of a branch as the PR title.

With Github CLI:

gh pr create --fill-first"

or Gitlab CLI:

glab mr create -t "`git log -1 --pretty=%B`" -y --fill --remove-source-branch --squash-before-merge

This sets the PR title and description to the last commit message in the branch.

Code reviews

PRs allow team members to review your code changes. Always target the ‘main’ branch with your PR.

For your PR:

Remember: git is a collaboration tool, not a reporting or deployment tool.

References