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
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:
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
orrun
directories 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
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.
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.