Create a Topic Branch

Before you start code development, let’s create a space that will hold your code changes in an easily identifiable way. You will want to make sure that you have access to the latest version of the code base available for you to make your changes to. Therefore, the branch will be created from an upstream branch. To do this, use the following commands from within your local athena repository:

git fetch upstream
git checkout -b my-topic upstream/[parent_branch] --no-track

Why git fetch upstream first? This is to make sure that your local repository is completely up to date with the main repository before you start work on your changes.

What is [parent_branch]? This is the release for which you are developing your code, which are maintained as branches, such as 24.0 and main. Giving upstream/[parent_branch] as the starting point ensures that you are starting from the most recent version of that code. In this tutorial we use upstream/main as this branch will always exist and be functional.

The -b option to checkout creates a branch and then checks it out, ready to work on. (It’s a shortcut for git branch ... plus git checkout ....)

git fetch upstream
git checkout -b my-topic upstream/main --no-track

We use --no-track to avoid git thinking you want to push and pull directly from upstream (this is more or less harmless, but can be confusing). If a parent branch were not given then the parent would be the current branch - you can use this form of branching when you want to use branches locally for tests or speculative development (it’s shown in every git tutorial under the sun).

Your new branch can be called a bugfix branch, a feature branch or a topic branch depending on it’s purpose (and which documentation you are reading). In this tutorial we’ll generally use the term topic branch.

The name of the topic branch can be anything, however, as in the normal workflow it’s visible to others when you make your merge request we recommend choosing a descriptive name, e.g., trk-optimise-selection. It is good practice to put the name of the branch you will merge into as a prefix to remind you what the target branch is.

Branching in git is very fast and cheap. Take advantage of this and use branches a lot to organise your developments.

You can check all of the origin and upstream branches git knows about with git branch -a. This allows you to see which target branches their are on the main repository (or you can also just browse the branches with GitLab).

If you started development before you made your topic branch…

It’s easy to do, but as long as you did not stage or commit your code, then git will keep your working copy changes in your checkout when you create your topic branch.

If you started editing a piece of code on the wrong branch then things are usually more difficult. Git will not allow you to change branches if a modified file is different in each branch:

$ git checkout my-topic
error: Your local changes to the following files would be
 overwritten by checkout:
	Tools/PyJobTransforms/python/trfExe.py
Please commit your changes or stash them before you
 switch branches.
Aborting

Using a git stash can be useful way to try to recover if you made significant changes you don’t want to lose.