GIT -- The Fast Version Control System

What is a GIT Repository? (by Matthias Kühnel)

A repository is a container for project files and a program, in this case 'git', handles the different versions of the files and takes care about merging of different file versions. That means many persons can work on the same project (or more precisely on the same files) simultaneously without taking care about the modifications of the other editors. So in principle each editor 'clones' the repository to his or her local computer, does some modifications and at last 'pushes' these changes back into the repository.

Clone existing repositories and add changes

Get repository clone

git clone

If you want to use or contribute to a repository, you will first have to get a full copy of it (called a "clone"):

git clone git@serpens.sternwarte.uni-erlangen.de:<group>/<repository>

where <group> is the group the <repository> belongs to .

Add changes to the repository

Before changing anything in the new clone it is good practice to work on a new branch.

git checkout

To create a new branch and change to it, use:

git checkout -b <branch-name>

Choose a representative branch name for the feature you want to add or change!

git add / git commit

In this fresh and new branch you can freely change anything you like. Keep your changes logically together and add/commit every time you start working on a new feature.

git add <filename1> <filename2> ...

adds all named files to the staging area. git status might prove useful as it will list all untracked changes.

When you have staged all necessary files, use

git commit

to apply your changes locally. (This will ask you for a commit message. See here for examples on how to explain what you did).

git push

With

git push origin <branch-name>

your changes will be added to the global repository (in the new branch). If the repository is located under gitlab and you want to provide your code for everyone it is probably necessary to send a merge request. (See here for more details).

git merge

To combine (merge) the branch feature with branch master of the same repository it is sufficient to call

git fetch origin
git checkout master
git merge feature

and probably also

git branch -d feature

to delete the branch in your local repository and/or

git push origin :feature

to delete the feature branch on the remote repository

Create your own repository

The most easy way to create a new repository (empty or from existing code) is to use the gitlab interface. Here you will also find first steps you want to do before start working.

However, if you do not want to use gitlab you can call

git init --bare --shared

in an empty folder. This, obviously empty, repository can then get pulled with

git sh://<user>@curx.sternwarte.uni-erlangen.de:/path/to/folder

and following the steps to clone a repository and add files.

Gitignore

For many projects (especially latex) it is very convenient to prevent you and others from adding temporary or unnecessary files. This can be done by creating a file called .gitignore in the root of the directory.

Example contents of .gitignore for a latex project:

#
# git ignore file for TeX files
#
*~
*.aux
*.log
*.bbl
*.blg
*.bak

In this example no file ending in ~, .aux, .log, .bbl, .blg, or .bak can get pushed to the repository. Be aware that .gitignore only prevents files from getting pushed. It does not affect files that are already part of the repository. So every file that is added before the .gitignore was added must be explicitly removed with git rm <filename1> <filename2> ... (also git push origin master to apply it to the remote repository).

Configure git

Every time you commit changes to a repository your message is appended with your name and mail address. If you have not specified a name and/or a mail address you can do this (globally) with

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

This will also overwrite existing entries, in case your mail address has changed.

Gitlab

The gitlab interface provides a powerful overview of all projects you are involved in. Also it gives you hints about what you should do with a fresh repository.

To create a new repository you first have to log in at www.sternwarte.uni-erlangen.de/gitlab

For creating the new repository just click on the "new project" button. Following the steps you will end up with a fresh repository.

Good commit practice

When you contribute to a repository there are a few rules for best practice which make life much more easier:

• every time you work on a new (or old) feature do your changes in a new branch with a meaningful name.
• commit frequently and each time for separate changes/features that are not related to each other
• commit messages should start with a <50 character summary in imperative mode. This is a headline! Capitalize the first word and no periods. A more complete description of what you did, where, and how, may follow after a blank line. Example commit message:

  Add awesome_feature
    
  This adds the awesome feature to foo by using the functionality
  bar. foo may now be unstable when used with out of range values.
  

  Although this message is very generic here, notice the ~80 character line break for better appearance.

  In general try to complete the following sentence with your summary: "With this commit you <insert summary here>"

  In the description explain why you did something, how did you accomplish it and what are the consequences.

Further information about good commit practice can be found on this web page.

Merge request

When you work on a repository located on gitlab, it might be necessary to fill a merge request. A merge request informs the maintainers of the repository that a new feature is available and ready for publication.

The easiest way to send a merge request is to follow the link that is given in your command line when you've pushed your branch.

On this page just select one maintainer to send the request to and check the mark for "delete branch after merge". You are not forced to delete your branch, but it is very good practice. Under normal conditions when you will work any further on the same feature (e.g., bug fixing) just checkout a new branch instead of keeping old ones. This will just lead to an unnecessary amount of dead branches.

Usefull git commands

git log	list log overview
git log --stat	list commits with stats
git log --oneline	display only first line of commit messages
git branch	list local branches
git branch -v	list local branches with more information
git branch -d <branch-name>	delete branch <branch-name>
git branch <branch-name>	add branch <branch-name>
git remote	list repository urls
git remote rename <old> <new>	rename <old> url to <new> url
git remote add <url-name> <address>	add new remote address under <url-name>
git push <url-name> <branch-name>	push <branch-name> to <url-name>
git push <url-name> :<branch-name>	delete <branch-name> from remote <url-name>
git status	list untracked files/changes
git add <filename>	add <filename> to staging
git commit	commit staged changes

More information about the different tools of git can be found in the man page git <tool> --help or here.

git and latexdiff

Find the version you want to compare your current document with via

 git log 

produce a pdf showing the differences between the two files via

latexdiff-vc --git --flatten -r long_weird_number_of_the_older_commit --pdf --disable-citation-markup file.tex

No need to checkout the older version! See latexdiff documentation for further options.