GitLab for version control

For any work you do at ATLAS you should store your code (and documents) inside a version control system. A version control system allows to keep “snapshots” of your files, allowing you to recover older versions of your code, see what changes where made when (and why/by whom), and to share code more easily between multiple machines and multiple users. To get you used to good practices we will have you record the work you do in version control throughout the tutorial, just like you ought to do for your actual analysis or documentation writing.

For ATLAS we generally use git for version control. With git you have your code (and code history) available in at least two locations: one is your local machine and the other is the gitlab server (some projects use github instead). To get you started with this tutorial, we prepared a basic analysis package with a single algorithm on gitlab. As a first step, you should make a remote copy (a.k.a. fork) of this “repository” on gitlab, so that you can modify it and upload your changes without those changes being visible to other people. For a real project (in which you’d generally want to share your changes) you’d also have to make “merge requests” to ask for these changes to be included in the main repository. We won’t be covering that in this tutorial, but details (along with other git details) can be found in the Git Workflow Tutorial.

Some best practices for version control:

Make regular commits (i.e. frozen checkpoints of your code), to keep your changes small and (ideally) focused on a single issue.
Check your changes before making a commit (with git diff --staged).
Only commit changes when your code is actually working.
Write a meaningful commit message describing the changes (if you can).
If you work with others on the same repository, create merge requests for your changes and have one of your collaborators review them. While this creates a bit more work upfront, it helps in both spotting potential problems early and in training new collaborators.
It is generally bad practice to keep commented-out code in your repository. You can always recover code from your git history with relative ease, and outdated commented out code can clutter up the current version of your code.
Only store primary files in the repository, not files produced from them, e.g. we keep our source code files in source in the repository, but not the files generated by compiling. It is good practice to compile your code in a separate directory from the source code itself to avoid accidentally adding automatically generated files to the git repository.

Forking The Repository

The skeleton is available here but in order to do your own development and track it using git, you need to first create your own version of it. This is done by forking the repository into your own GitLab account.

To do this, click on the Fork button on the project’s front page:

This will take you to a page where you can select a few options for the fork. The main options you need to configure are the project URL and the visibility level. Under the Project URL dropdown menu, select your name as the namespace and for Visibility level, select Internal. Then click on Fork project

If the project is successfully forked, you will be redirected to the new project under your namespace with the following message at the top:

Cloning The Repository Locally

Now we will clone (i.e. copy) the repository into your local area where you will do the code development.

You can see the various cloning options by clicking on the Clone button:

Navigate to AnalysisTutorial/source and check out the analysis package skeleton using ssh authentication with the following command (if you have your ssh keys set up):

git clone ssh://git@gitlab.cern.ch:7999/[YOUR_USER_NAME]/MyAnalysis.git

or, if you don’t have your ssh keys set up, using https authentication with the following command:

git clone https://gitlab.cern.ch/[YOUR_USER_NAME]/MyAnalysis.git

where [YOUR_USER_NAME] is replaced with your GitLab username.

Make sure you check the repository out into your source directory. This isn’t strictly necessary in general, but all of the commands in this tutorial assume this structure.

Navigate into the newly checked out directory with:

cd MyAnalysis

This is the local git repository (as indicated by the hidden directory .git) where you will develop and test your analysis code.

You should only use git repositories to version control code (and documentation, but that is beyond the scope of this tutorial). Do not keep your build or run directories in a git repository because they are filled with automatically created (and therefore reproducible) files that are regularly updated.

Committing Changes

When developing code as part of a team, such as developing ATLAS analysis code, it is important to regularly commit your changes and push them to a remote repository to make the most recent changes available.

From anywhere within your repository, you can check which files have been added, modified, or deleted since your last commit using the command

git status

If there have been no changes since the last commit, you will see the following message:

nothing to commit, working directory clean

If there have been any changes, you will see a list of files (if any) under Changes to be committed: and others under Changes not staged for commit:. Files listed in the former category will be recorded in your next commit. Files in the latter category can be staged to be recorded in the next commit with the following command:

git add <relative path and filename>

You can confirm that the files you add are properly staged using the git status command again.

The AnalysisTutorial/.gitignore file includes a list of files and patterns that git will ignore when looking for changes. You can add additional files to this as needed. Generally this should be used for files that are automatically (re)generated from compilation or temporary files created by your editor (e.g., *~ files created by vim).

Before committing your staged changes, confirm that you are committing exactly what you are expecting with the command:

git diff --staged

Commit your changes using the following command:

git commit

This will bring up an editor for you to write your commit message in. Write a meaningful message that describes what changes are included in the commit. When you save and quit, the commit will be completed.

You can set your preferred test editor for git (and any other programs that require one) by adding export EDITOR=vim (or whichever editor you prefer) to your .bashrc file.

You can also provide a commit message by command line with the command:
git commit -m "<commit message>"
Replace <commit message> (while keeping the quotation marks) with a descriptive commit message.

You can confirm that your commit is correctly recorded using git log.

Finally, use the following command to push your changes to your remote repository:

git push

Now you should be able to see your changes and a list of your commits in your repository on GitLab. You can do this using your browser with the URL https://gitlab.cern.ch/[USERNAME]/MyAnalysis where you replace [USERNAME] with your git username.

Try adding some text to README.md and commit and push your changes to test out the procedure.

You will be asked to regularly commit and push your changes throughout this tutorial. While this isn’t strictly necessary for a project you are developing alone, it is important to build the habit of doing so regularly.

Checking Your Work

As you proceed through the Analysis Algorithm part of the tutorial, you will likely want to check your code against solutions. You are strongly encouraged to first try to understand the code and debug any issues you encounter yourself or with your peers, followed by seeking help from the tutors. Nonetheless, it can be beneficial to be able to see a complete solution, which you can access here.