Clone Repository Locally

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

a full checkout gives you access to working copies of all files. It’s great if you want to look at many files or substantial parts of the repository (it’s very much the standard way that things would normally go in git, but you do need to setup more by hand).
a sparse checkout gives you only the parts of the repository you want to update. It’s great if you know you only want to make a limited set of changes and want to limit the space used by your working copy (it’s less standard, but git can do it and we provide the git atlas wrapper to make it easier).

Do not follow both sets of instructions - pick just one.

Full Checkout

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 run git 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 the athena 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 on lxplus:/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).

Add the main repository as upstream

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 and makefile 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.

Sparse Checkout

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.

About `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.

Using SSH keys to communicate with GitLab

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.

Go to your home directory.
Go to the .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.
Issue the following command:

ssh-keygen -t ed25519 -C "<comment>"

Accept the suggested location (which will be in the .ssh directory).
Specify and confirm a password.
Open the public key file (id_ed25519.pub) and copy the contents
Sign into gitlab.cern.ch.
On the left hand sidebar, click on your symbol - this may be an avatar if you picked one, or a letter representing your name.
Select Edit profile.
On the left sidebar, select SSH Keys.
Select Add new key.
In the Key box, paste the contents of your public key that you copied earlier. Make sure you copy the entire key.
In the Title box, type a description.
Select Add key.

Now, to clone the repository using ssh, do the following: