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:
git diff --staged).
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
Visibility level, select
Internal. Then click on
If the project is successfully forked, you will be redirected to the new project under your namespace with the following message at the top:
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
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://email@example.com: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
[YOUR_USER_NAME] is replaced with your GitLab username.
Navigate into the newly checked out directory with:
This is the local git repository (as indicated by the hidden directory
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
rundirectories in a git repository because they are filled with automatically created (and therefore reproducible) files that are regularly updated.
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
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)
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 statuscommand again.
AnalysisTutorial/.gitignorefile 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:
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
You can also provide a commit message by command line with the command:
git commit -m "<commit message>"
<commit message>(while keeping the quotation marks) with a descriptive commit message.
You can confirm that your commit is correctly recorded using
Finally, use the following command to push your changes to your remote repository:
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
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.