Git branch descriptions
It is common when experimenting with code to create many branches to test features. However, returning to a previous solution can be challenging if you do not remember exactly what was tested in a specific branch. You may need to go over all commit messages or switch to the branch to see its purpose.
On the following git history, it was difficult to remember what was done on ffmpeg branch:
Git has a very useful, but not very well-known, feature that can help with this problem: branch descriptions. However, even if you use this feature and add a description to a branch, most Git interfaces will not display it. Nonetheless, it is certain that the Git command line can display the branch description.
Despite these inconveniences, Git branch descriptions may be a better option than using external tools like Trello or Excel to keep track of branch descriptions. Since branch descriptions are stored directly in Git, they can be easily accessed and managed from the command line, without the need for additional tools or workflows. Additionally, using Git branch descriptions helps to keep all information related to the branch in one place, which can simplify project management and collaboration.
Adding description
You can add a description to a branch using the git branch --edit-description command. Here are the steps to do it:
- Make sure you are on the branch that you want to add the description to.
- Run the following command:
git branch --edit-description. This will open a text editor where you can add your description. - Type in your description and save the file. The description should be added to the branch.
Alternatively, you can also add a branch description directly from the command line using the -m option. For example, git branch -m my_branch -m "This is my branch description" will rename the branch my_branch and add the description "This is my branch description".
Reading description
You can see the description of a Git branch using the git config command. Here’s the command you can use:
git config branch.<branch-name>.description
Replace <branch-name> with the name of the branch whose description you want to see. For example, to see the description of a branch named feature-branch, you would use the following command:
git config branch.feature-branch.description
If the branch has a description, this command will output the description to the terminal. If the branch does not have a description, the command will not produce any output.
Note that the git config command reads configuration values from a .git/config file located in the root directory of your Git repository. If you’re working with a remote repository, you won’t be able to see branch descriptions for branches that are not present in your local repository.