How version control with Git works is best explained in some tutorials or books avail-able in the web [Git;CS14]. In the following, I introduce a few of the most important features and commands to use Git in the context of BTDFT.
Currently, the root Git repository is located in the file system of the IT service center of the UBT. The root repository is a pure repository without working directory to allow for ’push’ commands as explained below. There is one master branch and one extra branch for each person who works with the code to allow for a parallel development.
There are different user privileges: normal users and administrators. The only difference between them is that only administrators are allowed to ’push’ commits onto any branch of the root repository, specifically the master branch. Normal users can only ’push’ onto their own branch named by their own user identifier (usually the bt- or s1- identifier) to prevent confusion. If a piece of code shall enter the master branch of the program, I recommend to merge the branch of the normal user into the local master branch and let the administrator do the ’push’. This behaviour is controlled by Git hooks and explained in one of the following paragraphs.
Getting started First of all, practical information on how to use git in the context of BTDFT can also be found in the file BTDFT.README, which is located in the same directory as the root repository itself.
To start with an own working copy of BTDFT, the root repository must be cloned.
This is done by ’git clone [parent repository]’ in the directory where the local working repository shall be generated. This way, a new directory called BTDFT/ will appear with the underlying file tree (see appendix A.1).
Change to the BTDFT/ directory (’cd BTDFT/’). By default, only the master branch is checked out. A list of existing branches can be printed using ’git branch’.
To set up a new branch with the bt-identifier, call ’git branch [identifier]’. To check out the new branch, call ’git checkout [identifier]’. In the local repository, there should now be a new branch labeled with the identifier (check with ’git branch’). To generate the branch with the same identifier in the remote root repository, type ’git push origin [identifier]’. The ’origin’ keyword in the last command identifies the remote git repository the local repository was cloned from. As a normal user, this does only work with your own bt-identifier. Still, every one can pull every other branch from the remote root directory by ’git pull [remote repository identifier] [branch name]’.
Useful commands
• Add a (modified) file to the git repository (or more precisely: to the staging area): ’git add [file]’
• Output status information about files that are untracked, modified, etc.: ’git status’
• Ignore files that fit a certain pattern: Edit the file BTDFT/.gitignore
• Commit your changes (after you added them via ’git add’ to the staging area):
’git commit’
• ’git commit’ asks you to comment the commit. The commit history (log) is output via ’git log’
• List tags: ’git tag’
• Show the difference between the current working directory and the last commit:
’git diff’
• ’git diff’ can also be called with further arguments to list the differences between arbitrary commits.
• Create a new branch: ’git branch [branch name]’
• Switch to a branch (checkout): ’git checkout [branch name]’
• Merge one branch (’feature’) into another branch (’develop’):
– ’git checkout develop’
– ’git merge feature’
– If necessary: resolve merge conflicts manually and commit your changes
• Delete a branch: ’git branch -d [branch]’
• Restore a file to the state of your last commit: ’git checkout -- [file]’
• Create a tag: ’git tag -a [tag name] -m [comment]’
Workflow In the work with BTDFT, Git can be ignored completely. Nevertheless, it helps a lot with the development. This is especially true if there is more than one programmer since the coordination of different code versions and merges is quite simple. Still, even for a single developer, it is quite handy to go back and forth in the commit and release history to track changes and bugs. Therefore, I present the workflow I used in the development of BTDFT in the following (see [Git;CS14]).
In the local repository, there should be at least two branches: masterand the branch of the user labeled with the bt-identifier, e.g.,bt123456. The master branch contains the official version of BTDFT and can be updated from the remote repositoryorigin via ’git pull origin master’ if there has been a new release. The branchbt123456should be the own stable branch.
For the development, a local development branchdevelopcan be generated through
’git branch develop’ and ’git checkout develop’. After the implementation of new features, the changes can be merged back into the stable branch via ’git checkout bt123456’ and ’git merge develop’. Thedevelopbranch itself can also be branched into several feature branches. Branching in Git is very cheap, since it only uses pointers to certain commits. Thus, extensive branching is recommended. Also, tagging important commits is recommended since they are easily checked out later.
Publishing via ’push’ In order to publish the new code, the own bt-branch (e.g., bt123456) can be pushed onto the corresponding branch of the remote repository. This is done by ’git checkout bt123456’ and ’git push origin bt123456’. To push tags, run
’git push --tags’. If the work shall enter the master branch the project administrator can merge thebt123456 branch into the master branch and push it.
Project administrator As mentioned before, only the project administrator can
’push’ onto the root master branch while normal users are only allowed to push onto their own branch in the root repository. The corresponding settings are done via Git hooks in the file ’hooks/pre-receive’ inside the root repository.
Generation of the root repository The information in this paragraph explains, how the root repository has been setup and is just for documentation. The root repository has been created from an initially existing git repository which is called local in the following.
• Change directory to the location of the new root repository
• Make directory for the repository:
’mkdir BTDFT.git’
’cd BTDFT.git’
• Initialize git with options ’--bare’ (no working directory, ’push’ is only allowed to a bare repository) and ’--shared’ (repository is shared, all who have write access are in principle allowed to push):
’git init --bare --shared’
• Change the group of the repository to ’btpc’, allow group write access and restore the SGID bit for all directories (applied to directories, this ensures that the access rights of a directory are handed down to the child directories and files.
The SGID bit is set by the ’--shared’ option of ’git init’ but destroyed by the
’chgrp’ command below. Therefore, it has to be restored because otherwise no one would be allowed to ’push’ to the remote repository):
’chgrp -R btpc BTDFT.git’
’chmod -R g+w BTDFT.git’
’chmod -R g+s ‘find BTDFT.git -type d‘’
• Add the new remote repository as originto the local repository and ’push’ the branch with the latest BTDFT version to the new remote repository:
’cd [local repository]’
’git checkout master’
’git remote move origin origin_old’ (move the oldoriginrepository toorigin_old or remove it if it is not used anymore via ’git remote remove origin’)
’git remote add origin [remote repository]’ (add the new remote repository as new origin)
’git push origin master’ (’push’ the local master branch onto the new remote master branch)