IHEP GitLab

IHEP supplies a GitLab server, which allows you to put your analysis code in a git repository. You can then enjoy all the benefits of version control, different branches to collaborate as a team, a better overview through online access, etc. The IHEP GitLab server can be accessed through code.ihep.ac.cn. Have a look here at what git does, it’s worth it!

Note

Unfortunately, the IHEP GitLab server is only available on-campus through the LAN network. In theory, it is possible to connect through the IHEP VPN (ssl.ihep.ac.cn) using EasyConnect, though to set this up, you will first need to be in that LAN network. There are plans to make the server available through the standard SSO account.

Preparing access to the server

To be able to push files to a repository on the IHEP GitLab server, you will first need to apply for an IHEP GitLab account. You can do this by sending an email to fanrh@ihep.ac.cn.

When you have received your login credentials, log in to code.ihep.ac.cn and have a look around. As you have probably noticed, there is a warning that you have to add an SSH key in order to pull and push to the server. The steps to create such a key are comparable to those for login in to the IHEP server.

1. Generate an SSH key with the command ssh-keygen. You can choose to leave the password empty.

2. Add the SSH key to the ssh-agent and create a corresponding public key with the commands:
   eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa

3. Now, obtain the corresponding public key using:
   cat ~/.ssh/id_rsa.pub
   and copy all the text you see there (from ssh-rsa to @ihep.ac.cn).

4. Go to code.ihep.ac.cn/profile/keys, click “Add SSH Key”, paste the code there, and “Add key”.

5. That’s it!

See here for more elaborate instructions.

As a test, you can now create a new repository on the server. Just click “New project” and follow the instructions. This is a nice way to start, as you will be immediately shown instructions on how to configure git locally (such as setting the user name).

Pushing existing code to a new repository

Imagine the situation where you have already developed some code for your analysis and you want to start tracking it using git. Let’s say the directory containing this called is TestRepo. Here, we go through the steps required to put that code into a repository and push it to the IHEP GitLab server.

Step 1: Go to the files you want to track

Go to your the folder containing your code or, alternatively, make a directory (mkdir), and add some test files there.

Step 2: Initialize the repository

Initialize this folder as an empty git repository using:

git init

The name of the repository that you just initialized is the name of the folder.

Step 3: Add the files in the directory

Files in the directory are not tracked by git automatically. You have to add them manually. This can be done through the git add command, for instance:

git add temp.sh
git add config/testfile.txt
git add src/
git add inc/*.hpp
git add .

You now have staged these files, that is, made them ready for a commit to the repository. Files that have been added, will be tracked from then onward: if you change such a file git allows you to compare the changes, move back to older version, compare the file to its counterpart in parallel branches, etc.

Note that the paths are relative and that you can use git add from any subdirectory in the repository.

.gitignore

If there are certain files you never want to track (such as input data files or output plots), you ‘shield’ them by creating a file called .gitignore (note the dot) in the main directory of the repository. This is a text file contains relative paths of the files you want to ignore. Wildcards are allowed, see here for more information. Now, if you use git add ., all new or modified files in the folder will be staged, but for the ones excluded by .gitignore.

Step 4: Commit the changes

Once you have added the files, you can make commit the changes using:

git commit -m "<some description>"

This will basically create a new point in the history of your git repository to which you can move back any time.

Step 5: Check the status of the repository

Some commands that are useful from this stage onward:

• Use git status to check which files have been tracked, which ones are modified compared to the previous commit, which ones removed, etc. If you added all the files you wanted to add, you can commit or push.

• Use git log to see the history of all your commits.

• Use git diff <relative path> to compare the differences in a tracked directory or file with its previous commit.

• Use git checkout <relative path> to retrieve the previous version of the file or directory.

• See here for a full reference of git commands.

Note

The above 5 steps are all you need to know if you just want to track your files through Git locally. You do not have to work with a GitLab server, though of course this does allow for team collaboration and is the best way to backup your work.

Step 6: Configure the Git repository

If you have applied for an account and added an SSH key, you can push this new repository to code.ihep.ac.cn. If you haven’t already done so, set the user name and email address for this repository:

git config user.name "<Your full name>"
git config user.email "<email>@ihep.ac.cn"

Use git config --global if you want to use these credentials everywhere.

Now you can add the SSH location to which you want to write your repository:

git remote add origin git@code.ihep.ac.cn:<username>/TestRepo

Here, <user name> should be the one you were given when you registered. Here, we use the directory name TestRepo as repository name, but it can be any name as long as it is unique within your account.

Step 7: Create the repository on the server

Unfortunately, access through SSH does not allow you to create a new repository on the server, so you have to do this through the web interface.

Go to code.ihep.ac.cn and click “New repository”. Use TestRepo as the “ Project name”, then click “Customize repository name?” to ensure that the name of the repository is TestRepo as well. (If you don’t, it will be named testrepo, while the repository name should match the name of your directory. As you see, the default option for a new repository is private, so only you can see it.

Step 8: Push your the first commit

Now, back to your files, you can push the commit you made to that new TestRepo on the server:

git push -u origin master

Later, you can just use git push without arguments, but this is to force the first commit to the master branch.

That’s it, the connection has been established!

You can now edit and add files and then go through steps 3 (add), 4 (commit), 5 (status), and 8 (push) to track your files.

Note

If you work together with others, you can use git pull to get the latest changes that others added. Working together through git is, however, a bit more complicated because you’ll have to think about different branches and how to deal with merge conflicts. Have a look at the Git Handbook for more information.