====== git for users ======

git.math.uni-sb.de

====== Basic git commands ======

If you are not familiar with git, read an introduction, e.g. [[https://git-scm.com/book/en/v2/Getting-Started-Git-Basics]].

A good overview over basic git commands can be found at 
[[https://confluence.atlassian.com/stash/basic-git-commands-278071958.html]].

====== git synchronize with a server ======
===== Preparations =====

==== ssh ====

To access the git server you need to send your **public** ssh key to a system administrator, e.g. ''systemverwaltung@math.uni-sb.de''.

If you do not have a ssh key, create one with
   ssh-keygen -t rsa -b 4096
Always use a password to protect your key.
The public ssh key is usually stored ''~/.ssh/id_rsa.pub''.

**Remark**: Never distribute or delete your private key ''~/.ssh/id_rsa'' .


Our git server is ''git@git''.
We use gitolite on the server, the full documentation can be obtained by
  ssh git@git help

You can check your repositories and permissions with
  ssh git@git info

**Remark:** the output of the previous commands tells you the structure of repository names, usually it is
''u/<user>/<name>''.

==== git  ====

Before you can push changes to a remote git repository, ''git'' needs to know your ''name'' and ''email''.
There are two ways.

=== On the console ===

  git config --global user.name <name>
  git config --global user.email <email>
  git config --global push.default simple
  
=== With a config file ===
Add or modify the ''[user]''-section of ''~/.gitconfig'':

<file>
[user]
	name = <name>
	email = <email>
[..]
</file>



=====  Manage Repositories =====

Create a new repository 
  ssh git@git create <repo_name>

Delete repository
  ssh git@git D unlock <repo_name>
  ssh git@git D rm <repo_name>

Clone existing repository
    git clone git@git:<repo_name>

Import existing git repository
<code>
git remote add origin git@git:<repo_name>
git push origin master

git pull 
Error: ...You asked me to pull without telling me which branch you...
 
git config branch.master.remote origin
git config branch.master.merge refs/heads/master
</code>

===== Manage Permissions =====

Check who has access to your repo 
  ssh git@git perms -l <rep_name>

Give someone read (READERS) or read+write (WRITERS) access to your repo
  ssh git@git perms <repo_name> + <READERS or WRITERS> <username>
With a minus sign you can remove the permissions again.

===== Access from outside =====

To access the git server from outside university, e.g. from home, run 
  ssh-copy-id -i ~/.ssh/id_rsa.pub <your username>@math.uni-sb.de

and add the following lines
to ''~/.ssh/config''
<code>
Host git
  Port 22
  ProxyCommand ssh <your_username>@contact.math.uni-sb.de -W %h:22
</code>
Then the previous commands should work as if you were at in the mia network.

====== German: git-Anleitung ======

===== Neues Repository erstellen =====

erstelle ein neues Verzeichnis, öffne es und führe
  git init
aus, um ein neues git-Repository anzulegen.

===== Ein Repository auschecken =====

erstelle eine Arbeitskopie, mit folgendem Befehl:
  git clone /pfad/zum/repository
Für ein entferntes Repository benutze diesen Befehl:
  git clone benutzername@host:/pfad/zum/repository

===== Arbeitsablauf =====

Das lokale Lager (Repository) besteht aus **drei "Instanzen"**, die von ''git'' verwaltet werden. 
Die erste ist die persönliche //Arbeitskopie//, welche die echten Dateien enthält. \\
Die zweite ist der //Index//, welcher als Zwischenstufe agiert und 
zu guter Letzt noch der \\
//HEAD//, der auf deinen letzten Commit zeigt.

===== add & commit =====

Du kannst Änderungen vorschlagen (zum //Index// hinzufügen) mit
  git add <dateiname>
  git add *
Das ist der erste Schritt im git Arbeitsablauf, die Änderungen bestätigt man mit:
  git commit -m "informative Commit-Nachricht"
Jetzt befindet sich die Änderung im //HEAD//, aber noch nicht im entfernten Repository.

===== Änderungen hochladen =====

Die Änderungen sind jetzt im //HEAD// des lokalen Repositories. Um die Änderungen an das entfernte Repository zu senden, führt man: 
  git push origin master
aus. ''master'' kann man auch mit einem beliebigen anderen //Branch// ersetzen, mehr über //Branches// weiter unten ([[#Branching]]).

Wenn das lokale Repository nicht von einem entfernten geklont wurde und dieses aber mit einem anderen Repository verbunden werden soll, so fügt man dieses mit
  git remote add origin <server>
hinzu. Jetzt ist alles bereit, um die Änderungen hochzuladen.

===== Branching =====

Branches (Verzweigungen) werden benutzt, um verschiedene Funktionen isoliert voneinander zu entwickeln. Der master-Branch ist der "Standard"-Branch, wenn ein neues Repository erstellt wird. Für die Entwicklung sollte man andere //Branches// verwenden und diese dann in den //Master-Branch// zusammenführen (//mergen//). Dazu später.

Einen neuen Branch mit dem Namen "feature_x" erstellen und dorthin wechseln:
  git checkout -b feature_x
Um zum Master zurück zu wechseln:
  git checkout master
Und um den eben erstellten Branch wieder zu löschen:
  git branch -d feature_x
Ein Branch ist nicht für andere verfügbar, bis er zum entfernten Repository hochgeladen wird:
  git push origin <branch>


===== update & merge =====

Um ein lokales Repository mit den neuesten Änderungen zu aktualisieren (update), verwende man
  git pull
in der lokalen Arbeitskopie, um die Änderungen erst herunterzuladen (fetch) "pull" und dann mit dem lokalen Stand der Arbeit zusammenzuführen (merge).
Wenn man einen anderen //Branch// mit dem aktuellen (z.B. master) zusammenführen will:
  git merge <branch>
In beiden Fällen versucht ''git'' die Änderungen automatisch zusammenzuführen. Unglücklicherweise ist dies nicht immer möglich und endet in Konflikten. Jeder Nutzer ist verantwortlich, diese Konflikte durch manuelles Editieren der betroffenen Dateien zu lösen. Die Beendigung dieser Arbeit teilt man ''git'' mit folgendem Befehl mit:
  git add <dateiname>
Bevor Änderungen zusammengeführt werden, kann man die Unterschiede (Differenzen) anschauen:
  git diff <quell_branch> <ziel_branch>

===== Tagging =====

Es wird empfohlen, für Software Releasestags zu verwenden. Dies ist ein bekanntes Konzept, das es schon mit SVN gab. Du kannst einen neuen Tag namens 1.0.0 mit folgendem Befehl erstellen:
  git tag 1.0.0 1b2e1d63ff
1b2e1d63ff steht für die ersten 10 Zeichen der Commit-Id, die du mit deinem Tag referenzieren möchtest. Du erhältst die Liste der Commit-IDs mit:
  git log
Du kannst auch weniger Zeichen verwenden, es muss einfach eindeutig sein.
Änderungen rückgängig machen

Falls du mal etwas falsch machst (was natürlich nie passiert ;) ) kannst du die lokalen Änderungen mit:
  git checkout -- <filename>
auf den letzten Stand im HEAD zurücksetzen. Änderungen, die du bereits zum Index hinzugefügt hast, bleiben bestehen.

Wenn du aber deine lokalen Änderungen komplett entfernen möchtest, holst du dir den letzten Stand vom entfernten Repository mit folgenden Befehlen:
  git fetch origin
  git reset --hard origin/master

====== git extras ======

===== git-GUI: =====

  gitk

===== Colored console output: =====

  git config color.ui true
  
===== One line for every commit in log output: =====

  git config format.pretty oneline
  
===== Interactive adding of files to git: =====

  git add -i

===== Disconnect from git repository: =====

  git remote remove <name>

remove, rm
Remove the remote named ''<name>''. All remote-tracking branches and configuration
settings for the remote are removed.

===== Rename git repo: =====

  git remote rename <old> <new>
  
Rename the remote named ''<old>'' to ''<new>''. All remote-tracking branches and configuration
settings for the remote are updated.
In case <old> and <new> are the same, and <old> is a file under ''$GIT_DIR/remotes'' or
''$GIT_DIR/branches'', the remote is converted to the configuration file format.