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>
</ref>

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.

<pre>
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 Git--The_Fast_Version_controll_system#Good_commit_practice 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 #Merge request 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_existing_repositories_and_add_changes 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.

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.