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 fromupstream
(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).
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.