You now have a GitLab fork of your own, but this is used primarily for sharing your changes with others. But to make a change you need a local copy that you can edit yourself. In git this is done by cloning your fork.
Here there are two ways to proceed
git atlas
wrapper to make it easier).Do not follow both sets of instructions - pick just one.
The standard git clone
command will take a copy of the repository
and checkout a working copy for you:
# cd /tmp/$USER # you might need this, read the note below
git clone https://:@gitlab.cern.ch:8443/[YOUR_USER_NAME]/athena.git
i.e.,
$ git clone https://:@gitlab.cern.ch:8443/graemes/athena.git
Cloning into 'athena'...
remote: Counting objects: 232197, done.
remote: Compressing objects: 100% (99543/99543), done.
remote: Total 232197 (delta 125192), reused 231903 (delta 125033)
Receiving objects: 100% (232197/232197), 160.35 MiB | 37.61 MiB/s, done.
Resolving deltas: 100% (125192/125192), done.
Checking connectivity... done.
Checking out files: 100% (68190/68190), done.
This will give you a local copy of athena
in the directory where you run this command.
On platforms other than LXPLUS, you may experience the following error:
The provided password or token is incorrect or your account has 2FA enabled and you must use a personal access token instead of a password.
In this case you need to use a ssh key - see the instructions below on how to do this.
On CC7, you may experience the following error:
remote: HTTP Basic: Access denied
. To overcome it, please rungit config --global http.emptyAuth true
.
Actually cloning the repository information in git is extremely efficient. A few 100MB of information is downloaded to
athena/.git
and the many thousands of different revisions are stored in a compact form stuffed in a few summary files.
However, getting the working copy of the source code (a checkout, that clone also does by default) requires copying out the current versions of the 60k+ files in theathena
repository. On a local filesystem this is still fast. But on a shared filesystem, like AFS, this can be slow and take several minutes. So we do recommend using a local disk if you can. (Even doing the tutorial onlxplus:/tmp/$USER
is better than nothing.)
Note that GitLab offers a different ways to authenticate, so there are a few
URLs you could use to clone the repository. Use the Clone
dropdown on
the fork’s front page to get the one you want:
krb5
is the easiest to use from lxplus
or on any machine
where you can get a Kerberos ticket, https
works
well from modern git clients (like your laptop), ssh
requires
some extra setup (but works very well when this is done).
When code is developed it should begin from the current HEAD
version of the main repository. So we add the main repository as a
remote repository, called upstream
:
cd athena
git remote add upstream https://:@gitlab.cern.ch:8443/atlas/athena.git # or any other valid URL
Your local checkout now has two remotes, origin
(your fork) and
upstream
(the main repository):
$ git remote -v show
origin https://:@gitlab.cern.ch:8443/graemes/athena.git (fetch)
origin https://:@gitlab.cern.ch:8443/graemes/athena.git (push)
upstream https://:@gitlab.cern.ch:8443/atlas/athena.git (fetch)
upstream https://:@gitlab.cern.ch:8443/atlas/athena.git (push)
Visually it looks like this:
The arrows show how code gets into your local repository. The fork and clone have been covered. Fetching is next. Merge you shouldn’t normally need to do (and certainly not for the tutorial), but it is covered later.
On a Mac the default HSF+ partition is case insensitive, case preserving (i.e.,
Makefile
andmakefile
are the same file). This is known to cause issues with git repositories where files changed the case of their name, but did not change their content. This has happened a few times in the past with ATLAS offline code and can’t consistently repaired post facto. So on a Mac we recommend using a HSF+ disk image formatted to be case sensitive if you need to work with releases prior to 21.0.
Only follow these instructions if you did not do a normal clone of your repository above. Otherwise, just skip to the next section.
This feature is still in very active development. If you encounter any problems then feedback would be very welcome.
The normal checkout
above made a copy of all
the paths available in the repository. However, very often one wants to
only check out a few packages to work on. This is possible using the
git-atlas
wrapper.
setupATLAS
lsetup git
git atlas init-workdir https://:@gitlab.cern.ch:8443/[YOUR_USER_NAME]/athena.git
This will setup a sparse checkout but doesn’t check out any packages yet
(though it can, if you directly add package names at the end of the command).
It will also setup your fork as origin
and the main repository as upstream
.
The advantage here is that CMake will only build the packages you have
checked out similar to the work-flow with SVN.
To then add the PixelCabling
package to your checkout, run
cd athena
git atlas addpkg PixelCabling
This will checkout the PixelCabling
package (the full path resolves
to InnerDetector/InDetDetDescr/PixelCabling
), but leaves the other parts
out of the work tree.
Use addpkg
to add as many packages as you like, rmpkg
to remove
them and listpkg
to check what you have.
You can find additional information on git-atlas
here.
upstream
and origin
Whether you do a full or sparse checkout, you have associated
origin
(<username>/athena
) and upstream
(atlas/athena
)
repositories. As will be discussed in the next section, you
will create development branches from atlas/athena
to begin
with the latest available changes. While your topic branches
will live in your fork until they are merged into atlas/athena
,
most of the branches in your fork (e.g., <username>/athena/main
)
will quickly become out of date with respect to atlas/athena
.
This is not problematic since the workflow for the vast majority
of development bypasses these branches. There may be unique
circumstances in which updating non-topic branches in your fork,
but generally this will never be needed.
On platforms other than LXPLUS you are likely to need to set up SSH keys to enable secure communication between GitLab and your account. The full instructions can be found here and a quick reference is written here.
.ssh/
subdirectory. If it doesn’t exist, you are either not in the home directory, or you haven’t used ssh before. In the latter case, create the directory and cd
into it.ssh-keygen -t ed25519 -C "<comment>"
.ssh
directory).id_ed25519.pub
) and copy the contentsNow, to clone the repository using ssh, do the following:
git clone ssh://git@gitlab.cern.ch:7999/[YOUR_USER_NAME]/athena.git