Category: git

When working on a project tracked with git, you will sure do create branches. You have the main branch of course, but then a good practice is also to have one branch per features you are developing. Below what it might look like at then end:

> git branch
* master
  dev/JIRA-1234
  dev/JIRA-5487_add_users_filtering
  dev/add_google_sign_in_authentication_form
  dev/ISSUE-987

Let’s have a closer look on how to name them (even though the above snippet already gives you a hint).

Main branch

The main or master branch is treated as the unique source of truth, the official working code base. This is a place where everything must be working. It is the default branch you come up with when you initialize a new git project.

Notes:

• Since 2020 and 2022, Github and Gitlab (respectively) renamed their default branch from master to main to avoid language that might be seen as offensive.
• If you do not want to politicize git and still prefer the old naming convention, you can still rename main for master manually. How to rename git branch explains how to do it.

Feature branches

It is time to add features into our main branch. Since main is the place where everything must be working, you first want to test your changes on a development branch. Usually, you end up with 1 branch per feature. Each of them templated as follow:

dev/JIRA-1234
dev/JIRA-1234_add_users_filtering
dev/add_google_sign_in_authentication_form
dev/ISSUE-987

In a nutshell, the following rules apply:

• Prefix the non-main branch with dev/. It will makes easier to trigger the dedicated Gitlab CI jobs via branches filtering.
• If you use an issue tracker like Jira, include the ticket’s ID. Gitlab includes a Jira Integration facility tool e.g. creating links to the Jira ticket on the fly.
• Beside the ticket ID, stick to the good old snake_case. See also Why you should use Snake Case.
• If you do not use an issue tracker e.g. for personal projects, simply describe the feature you are implementing.

The difference between git checkout and git switch:

• Both are used to perform actions on branches (create, delete, navigate)
• git checkout is doing more than git switch
• git switch has been created to be more simpler

In practice, I always use git switch instead of git checkout. But let’s explore some use cases.

git switch

To switch to an existing branch:

git switch <existing-branch>

To create a new branch and directly jump into it:

git switch -c <new-branch>

Notes:

• The -c option is short for --create.
• There are rules regarding branch naming convention. See What are the git branch naming conventions.
• You can create an alias to write git sc <new-branch> instead of git switch -c <new-branch> (see How to create git aliases).

git checkout

To switch to an existing branch:

git checkout <existing-branch>

To create a new branch and directly jump into it:

git checkout -b <new-branch>

To delete a branch:

git checkout -D <deleted-branch>

Note: in practice you won’t have to delete a branch manually. This will be done automatically after merging the Pull Request (on Github) or Merge Request (on Gitlab).

Last few words

We haven’t explored the full capacities provided by both methods. However, we have seen that both of them provides overlapping logics. To go in-depth, you can dive into the official documentation:

• https://git-scm.com/docs/git-switch
• https://git-scm.com/docs/git-checkout

On more thing: we didn’t had the chance to stop and talk about git branch, a functionality allowing us to perform more actions on branches such as renaming a branch This will be done in another chapter (in progress).

Simply use:

git restore --staged <file>...

The aforementioned command will unstage the files staged for commit you have accidentally added via git add. However, this relies on you not having committed already. If you have committed but still want to undo the operation, see (in progress).

Example

You have added a couple of files to be staged for commit:

git add .

Following the best practices, you always check the status after such operations:

git status

At this point, you notice that a couple of unwanted files have been added into the list of files to be staged for commit:

On branch dev/VERS-5928
Your branch is up to date with 'origin/dev/VERS-5928'.

Changes to be committed:
(use "git restore --staged <file>..." to unstage)

    modified:   .gitlab-ci.yml
    new file:   .gitmodules
    modified:   Makefile
    modified:   README.md
    new file:   project_foo/__pycache__/__init__.cpython-310.pyc
    new file:   project_foo/__pycache__/main.cpython-310.pyc
    new file:   project_foo/__pycache__/utils.cpython-310.pyc

In our example, you do not want push the last 3 files into the remote repository. The simplest solution is then to undo the git add operation so those files are no longer staged for commit:

git restore --staged project_foo/__pycache__/__init__.cpython-310.pyc

You can then repeat the operation for the last 2 remaining files.

However, even though this manual manoeuver is easily doable in our relative simple case, what about if in place of 3 files, way more files should be deleted?

In such case, the workaround to undo git add operations before commit for multiple files is as follow:

git restore --staged $(git diff --name-only --cached | grep "__pycache__")

Notes:

• To undo the git add operation after commit, see (in progress).
• To know more about the git restore command (in progress).
• The difference between git reset, git restore and git rm (in progress).

To make it short, the main take-aways:

git branch -m <new-name>
git branch -m <old-name> <new-name>
git push origin -u <new-name>
git push origin -d <old-name>

Use case: local changes or project not yet existing on remote

To rename the current git branch:

git branch -m <new-name>

To rename any other git branches you’re not currently pointing at:

git branch -m <old-name> <new-name>

Tips:

• The -m option is short for --move. That way it’s easier to remember.
• Other custom-made shortcuts can be defined e.g. typing git b for git branch. Check How to create Git Aliases.

Use case: git project already deployed

If your git project is already deployed on a remote environment – e.g. Gitlab or Github – the beforementioned changes won’t be reflected though. To change the branches not only on local but also on the remote, you need to:

First, push the local branch and reset the upstream branch:

git push origin -u <new-name>

Then, delete the remote branch:

git push origin --delete <old-name>

Note: in that case, it is not necessary to use the git branch -m commands.

Use case: changing the capitalization

If you are only changing the capitalization – e.g. dev/vers-5395 becoming dev/VERS-5395 – you need to use -M instead of -m as Git will tell you that the branch already exists otherwise. This matters for users being on Windows or any other case-insensitive file systems.

Note: if you are wondering what might be a good branch naming convention, you can check the git branch naming conventions article.

Example

Github then Gitlab recently introduced changes to their main branch naming convention. By default, drifting from master to main. If you are a person used to the traditional way, you can restore the branch name, turning things more into your likings:

> git clone git@gitlab.com:username/your-project-in-kebab-case.git
> git branch
* main
> git push origin -u master
> git push origin --delete main

You can then check your changes:

> git branch
* master

Run the extra mile

If like me you’re still not 100% sure when it comes to git stash, rebase, forking and traveling back the history line, you can either:

• Have a look on this Git Learning path
• Start with the Git Basics.

But remember: it’s a marathon, not a sprint 🐢

To help you writing commit messages, there is a couple of guidelines, conventions and best practices one might follow. It can be summarized in 9 bullet points:

• Start with the ticket’s number the commit solves.
• Separate subject from body with a blank line
• Limit the subject line to 50 characters
• Capitalize the subject line
• Add issue reference in the subject
• Do not end the subject line with a period
• Use the imperative mood in the subject line
• Wrap the body at 72 characters
• Use the body to explain what and why, not how

Example

VERS-1936: Add user access to datapool table

Access rights for the datapool resource have
been edited. Access is required to work on the
new outfit recommender system. Request has been
approved by the PO.

Please, note the following:

• Access right is normally granted at the dataset level.
• Due to pii data, access was granted at the table level.

Resolves: VERS-1936
See also: VERS-0107

Additional notes

When you commit, the Vim editor will be called by default. You will be then asked to prompt your commit message. The big strength of Vim is that it is installed by default on all systems.

If you don’t want to call Vim but rather use the command line, you can use the inline -m flag to write your commit message:

    git commit -m "Your message at the imperative voice"

If you still want to use a text editor to fill-in the commit message, you can change the settings so it opens Visual Studio Code IDE when the git commit command is called:

    git config --global core.editor "code --wait"

This requires you to have Visual Studio Code installed though.

You are now fully equipped to write the next bestseller! 📚

Acknowledgement

• https://cbea.ms/git-commit/