View source for 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"):

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

where <tt><group></tt> is the group the <tt><repository></tt> belongs to
<ref>other repositories are distributed in the file system and can be obtained
via <code>git clone ssh://<user>@crux.sternwarte.uni-erlangen.de:/path/to/repo
</code>(always use this over <code>file://...</code> !)</ref>.

=== Add changes to the repository ===

Before changing anything in the new clone it is good practice<ref>it might be
necessary if the repo is located under gitlab</ref> to work on a new branch.

==== git checkout ====

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

<pre>
git checkout -b <branch-name>
</pre>

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> ...
</pre>

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

When you have staged all necessary files, use

<pre>
git commit
</pre>

to apply your changes locally. (This will ask you for a commit message. See
[[GIT -- The Fast Version Control System#Good commit practice|here]] for examples on how to explain what you did).

==== git push ====

With

<pre>
git push origin <branch-name>
</pre>

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
[[GIT -- The Fast Version Control System#Merge request|here]] for more details)<ref>In smaller projects it might
be sufficient to directly push to the master branch</ref>.

==== git merge ====

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

<pre>
git fetch origin
git checkout master
git merge feature
</pre>

and probably also

<pre>
git branch -d feature
</pre>

to delete the branch in your local repository and/or

<pre>
git push origin :feature
</pre>

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 [http://www.sternwarte.uni-erlangen.de/gitlab 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

<pre>
git init --bare --shared
</pre>

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

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

and following the steps to
[[GIT -- The Fast Version Control System#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 <code>.gitignore</code> in the root of the directory.

Example contents of <code>.gitignore</code> for a latex project:

<pre>
#
# git ignore file for TeX files
#
*~
*.aux
*.log
*.bbl
*.blg
*.bak
</pre>

In this example no file ending in <code>~, .aux, .log, .bbl, .blg,</code> or
<code>.bak</code> can get pushed to the repository.
Be aware that <code>.gitignore</code> 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 <code>.gitignore</code> was added must be explicitly
removed with <code>git rm <filename1> <filename2> ...</code> (also <code>git
push origin master</code> 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

<pre>
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
</pre>

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 
[http://www.sternwarte.uni-erlangen.de/gitlab 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:

<ul>
  <li>
  every time you work on a new (or old) feature
  do your changes in a new branch with a meaningful name.
  </li>
  <li>
  commit frequently and each time for separate changes/features that are not related to
  each other
  </li>
  <li>
  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:
<pre>
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.
</pre>
  
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.
  </li>
</ul>

  
Further information about good commit practice can be found on 
[https://chris.beams.io/posts/git-commit/ 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. 

= Useful 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
|}

<!-- add many more here -->

More information about the different tools of git can be found in the man page
<code>git <tool> --help</code> or [https://git-scm.com/docs here].

= git and latexdiff =
Find the version you want to compare your current document with via
<pre> git log </pre>

produce a pdf showing the differences between the two files via

<pre>
latexdiff-vc --git --flatten -r long_weird_number_of_the_older_commit --pdf --disable-citation-markup file.tex
</pre>

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

= Notes =

<!-- = Existing Repositories: How to clone and commit changes =

''The following text is copied from an e-mail from Joern concerning the software scripts of the Remeis observatory. More information one these scripts can be found at [[Software at the Remeis-Observatory]].''

== Get the files ==

If you want to modify scripts, you will first have to get a full copy
of the repository (called a "clone"):

  git clone ssh://account@crux.sternwarte.uni-erlangen.de/data/git/aitlib

(same for intscripts, xmmscripts, xtescripts, xspecscripts,
isisscripts, cyclo, fpipe) where account is your account at the
Sternwarte. 

Please use the above command EVEN IF YOU ARE WORKING locally in
Bamberg/Erlangen. Do NOT do a clone with the file://-syntax of git to
allow you to work on several machines (since the git push command will
not work properly). Just forget that file://... is an allowed git URL.

== Committing your changes ==

After doing the clone, edit the scripts and check them. In case you edit the isisscripts: Do not forget to <code>make</code> the isisscripts, i.e. compile your changes into the overall <code>isisscripts.sl</code> by typing
  make
in the <code>isisscripts/</code> directory.  
You should usually do your changes in smallish steps, i.e., applying a few changes,
checking them, and then committing them to the repository as follows: 

  git commit filename

OR

  git commit -a 

(the last if you've made changes to many files). This command will ask
you to enter information for the change log.

CONTRARY to CVS, a commit does not yet make your changes available to
others. This is advantageous, because it allows you to do commits
locally while you're developing a code, and then go back to an older
version once you realize that you've made a mistake. However, let's
assume that you've programmed something that is working and you want
to make it available to everybody. In this case, commit everything as
described above and then do a 

  git push

(do NOT forget this last command).

After you have committed and pushed your changes, WE STRONGLY
RECOMMEND THAT YOU REMOVE YOUR CLONED REPOSITORY (rm -r repo). The
reason is that experience shows that people often start working on
their "private" versions of the scripts and then either forget to
commit their changes (=nobody else gets access to them) OR they forget
to do regular updates of their local clones and then run into problems
that have already been fixed in the official repository. Access to the
current version of the scripts is better obtained using the approach
outlined below (and implemented on the Remeis machines, for example).

== Other useful commands ==
* assuming you've already cloned the repository and you want to update it to the newest version, use <pre>git pull</pre>

* to obtain a change log of the repository <pre>git log</pre>

* to obtain a change log for one file <pre>git log filename</pre> (which will work pretty much for all files, but for some reason does not work for the intscripts; note that even for the intscripts the full change log is still available and you can still check out older versions of the script should you desire to do so)

* to tag one of the commits with a tagname, e.g., to mark the submitted version of your paper as submitted, get the commit id from <code>git log</code> and do <pre>git tag 'tagname' id</pre> where tagname only needs quotes if it contains, e.g., spaces

* to push the tag<pre>git push --tags</pre>

* optimize the local git repository <pre>git gc --aggressive</pre> this will optimize the tree of stored local changes, removing intermediate data that are not needed anymore. This makes your local repository dramatically faster and can save significant space. You should run this every now and then (on very active directories probably once a week). 
  
* find out where the repository originally came from before it was cloned:<pre>git remote -v</pre>or for a little more information<pre>git remote show origin</pre>

* showing the differences between the old and new file:<pre>diff -u new_file old_file</pre>

= Create your own repository =

'' The following entry is from an email by Matthias Kühnel to Jieun (with additional comments added afterwards) and was intended to explain '''how to create a repository in order to edit a paper together using GIT'''.''

Now we'll create a git-repository for your paper: in your Remeis home
directory create a directory where to store all your repositories in,
such as ~/git (at the moment we'll create only one ;-)). Create a
subdirectory for your paper in there, ~/git/choi2011a for example.
Change into that directory and create an empty repository by
   git init --bare --shared
You should get a message like "Initialized empty Git repository in
/home/choi/git/choi2011a/". Add <code>--shared</code> only if everyone in your group should be able to 
commit changes.
All in all, this should create a structure of
files and subdirectories in your repository directory. Later your files
will be hidden somewhere in this structure (I'm not sure where to be
honest). The thing is that a bare repository only contains
modifications, that means no whole file, only different pieces depending
on the file version.
Now you have to modify the 'config' file of the repository (//note:// you should not need the following modifications if you initialized the repository with the <code>--shared</code> option), for example
   /home/choi/git/choi2011a/config
The file should look like<pre>
   [core]
        repositoryformatversion = 0
        filemode = true
        bare = true</pre>

Your repository is now ready to be used, but empty. So let's add some
files into it!

Create an empty directory somewhere that will contain your paper. We now clone your
(empty) repository into your source directory:
   git clone crux:/home/choi/git/choi2011a .
Note that we clone from machine <code>crux</code>, even if we are working on that machine. This approach will make your life easier if you are working on multiple machines in the Remeis cluster. Do not forget the trailing dot!

Now your directory is a clone of the repository. Copy all files and subdirectories that you would like to be part of the repository into the directory and then add these files to git
  git add filenames
where filenames can include (relative) paths to files somewhere in the directory tree of your repository.

A general rule for tex repositories for papers is to only add the source code and
*no* compiled or auxiliary files. That means, just add the .tex file,
any used styles (.sty) and images (.pdf, .ps, .eps or whatever). If you have
also isis scripts (.sl) which creates some plots, you may add them also.
Once you have added all necessary files, you have to 'commit' the changes:
  git commit -a
Now your default editor should open automatically, where you have to
enter a comment describing the changes (attention: the default editor should be set first in the ~/.cshrc, see [[csh:start|TC shell]]). This
comment will be put into the log. The editor also shows a list of files
which will be added/modified/removed. Please note that this list is for
your information *only*. Any changes to the list have no effect!
After you have entered a comment, quick save the file (if you use jed
Ctrl-X-S) and exit the editor (Ctrl-X-C). You should see something like:<pre>
  [master 5e91497] your_entered_comment
   1_or_more files changed, 3341_or_any_other_number insertions(+), 0
   deletions(-)
   create mode 100644 a_file_you_have_added
   ...</pre>
   
In order to avoid being prompted that unnecessary files such as editor backup files (e.g., filenames ending in a tilde or with .bak and other unnecessary files are not part of the repository, you can generate files called <code>.gitignore</code> in your git directories. These files contain descriptions of files which should not be in the repository. a <code>.gitignore</code> file is valid in the current directory and all of its subdirectories. These may contain further <code>.gitignore</code>-files. A good <code>.gitignore</code> for a paper would be:
<pre>
#
# git ignore file for TeX files
#
*~
*.aux
*.log
*.bbl
*.blg
*.bak
</pre>
Note that after creating the file you will have to add it to the repository! Files that were checked in before the .gitignore exists are not affected by adding the .gitignore, even if the filename is explicitly written down there. In this case, do a git rm [filename] and commit, and afterwards the file will not be checked in again.

That's a summary of the changes, which will be put into the repository
once you have 'push'ed them:
   git push origin master
Please note, that the usual command is
   git push
without the origin-master-stuff, which has to be done only once if an
empty repository was created!
If you modify previously added files later, you don't have to add them
again, of course. Instead skip the adding command and 'commit' and
'push' the changes directly.

Everybody knowing the path to your repository can now clone it, edit
files and push changes. To update your local copy with the repository
(i.e. to get the changes of somebody else) use
   git pull

= Committing only parts of the modifications =
''A further functionality Manfred finds particularly useful.''

It has been mentioned above that one can only commit selected files with

  git add file1 [file2 ...]  &&  git commit

(Do not use <code>git commit -a</code> in this case. If you really want to commit all changes, there is no need to first <code>git add</code> the files for this next commit.) 

It is also possible to <code>git add</code> only parts of the modifications, namely with the <code>-i</code>(nteractive) Option. When I run
  
  git add -i file1 [file2 ...]

and press <code>p</code> for (patch), 1 for the first file, and then hit [Return], I can decide for every changed block ("hunk") in file 1 whether (<code>y</code>) I want to add ("stage") this change to the next commit or not (<code>n</code>). If I want to commit only part of what git considers a "hunk" in first place, I can press <code>s</code> in order to split the current hunk. When I'm done with file 1 or when I quit with <code>q</code>, I can start over from the beginning, e.g. patching the next file.

After the desired hunks have been staged to the index, you run

   git commit

as usual, without <code>-a</code>!

= GIT Config =

Make sure to update your name and e-mail-address in your home under ''.gitconfig'' like<pre>
  [user]
        email = matthias.kuehnel@sternwarte.uni-erlangen.de
        name = Matthias Kuehnel</pre>

-->

[[Category:GIT]]