Git

This page is divided into the following sections:

Introduction

Before starting you should configure git:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Furthermore, it would be nice to have colored output (if you like it):

git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

The configuration will be stored in ~/.gitconfig

Creating a git repo

cd project-directory
git init

Let git take a snapshot of the working dir:

git add .

Now the contents is stored in a temporary staging area called "index"

git commit

Possible use modes

There are different use modes available when using git:

individual repo clones
Every user updates and clones against other users. This is only recommended when the developer team is very small.
master users
Every user clones against a master repo. When changes are to be committed, the master user will be informed and he will "pull" the changes from the user. Changes may be reviewed, accepted or declined. This is recommended when third-party developers try to commit code.
Shared repository
A central repo is cloned from the master repo being tagged as "shared". Users who clone the shared repo can "push" their changes to the shared repo. This is a probable choice for internal developers, see sections "Editing" and "Working with a shared repo"
A public repo serves as a public mirror which is not intended as working repository, but as interface for others in the outside world to fetch from.

TNG GIT REPO configuration

The following list of repositories has been created:

/home/tng/tng/SLangTNG which is the main (master) repo. It is accessible to the group tng. Only the user tng has write access.
/home/tng/tng/SLangTNG_public.git which is the public repo. It is accessible to the group tng_public. Only the user tng has write access.
/home/tng/tng/SLangTNG_shared.git which is the shared repo. All members of the group tng_shared have full access.

The following cron jobs have been defined:

Daily fetch all changes being made to the shared repo to the main repo (at 0:00 am).
Daily push all changes from the main repo to its public mirror (at 0:00 am).

Master repository

The repository of SLangTNG is located in

ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG

Clone the repository:

git clone ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG myrepo

which creates directory "repo" containing a copy of the repository. The copy is a real "copy" with its own history and management!

You can commit to your own repo as long as you wish. When being finished the main user (TNG master) must pull the changes from your repository:

cd /home/tng/tng/SLangTNG
git pull $HOME_OF_YOU$/myrepo master

All changes are merged into the master branch. The TNG master must solve conflicts if they appear.

One can check what the otehr user did without trying to merge:

git fetch /home/bob/myrepo master
git log -p HEAD..FETCH_HEAD

(show everything that is reachable from the FETCH_HEAD but exclude anything that is reachable from HEAD)

A visualization can be done using gitk or qgtk

 gitk HEAD..FETCH_HEAD

Remote repository

Define a remote repository (add user "bob"):

 git remote add bob /home/bob/myrepo

Using this, TNG master can fetch the changes without pulling:

 git remote add bob /home/bob/myrepo

The changes of bob are stored in an own branch ("bob/master") which can be reviewed. Let show the changes of bob

git log -p master..bob/master

and merge them:

git merge bob/master

Later, Bob can update his repo with the last changes of TNG master doing

git pull

The workflow is:

                                       user commits changes 
                                          to temp. branches
                                               |
                                               |
                      user pulls               V
  master repo   ----------------------->   user repo
  with changes                                 |
       ^                                       |                             
       | reviews changes and                   |  user merges possible conflicts and
       | merges user branch                    |  continues his work
       |                                       |                             
       |                                       V
  master repo  <-----------------------    user repo 
                    master fetches        with changes

Shared repository

For shared (trusted) access to a repository a local clone of the master repo has been created which is marked as a shared repository.

In order to clone the shared repository, type

git clone user@ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG_shared.git my-project
cd my-project

The workflow is:

                                                                     user commits changes 
                                                                     to temp. branches
                                                                      |
                                                                      |
               shared pulls                       user pulls          V
master repo ---------------------> shared repo --------------------> user repo
            <---------------------  ^                                 |
               master fetches       |                                 |
                                    |                                 | user merges possible conflicts and
                                    |                                 | continues to work
                                    |                                 |
                                    |                                 V
                                    +------------------------------- user repo with
                                                  user pushes        committed changes

Creating a shared repository

Assume that there is already a git repo existing, being located at

ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG

Create a new "bare" repository (a repository without a working tree) and fetch your project into it:

mkdir /home/tng/tng/SLangTNG_shared.git
cd /home/tng/tng/SLangTNG_shared.git
git --bare init --shared
git --bare fetch /home/tng/tng/SLangTNG master:master

Next, give every team member read/write access to this repository. One easy way to do this is to give all the team members ssh access to the machine where the repository is hosted. If you don't want to give them a full shell on the machine, there is a restricted shell which only allows users to do git pushes and pulls; see git-shell(1).

Put all the committers in the same group, and make the repository writable by that group:

chgrp -R tng /home/tng/tng/SLangTNG_shared.git

Note:

Make sure committers have a umask of at most 027 (particularly Ubuntu/Mac), so that the directories they create are writable and searchable by other group members.
Developers who are allowed to have shared access, must be part of group "tng". They have to clone the directory ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG_shared.git

Public repository

The public repository was created via

git clone --bare SLangTNG SLangTNG_public.git
touch /home/tng/tng/SLangTNG_public.git/git-daemon-export-ok

Users may fetch from this repo, but may not be able to push changes to it. The idea is that any developer has two repositories, a private and a public one. Then, the workflow is

                        you push
  your personal repo ------------------> your public repo
    ^                                     |
    |                                     |
    | you pull                            | they pull
    |                                     |
    |                                     |
    |               they push             V
  their public repo <------------------- their repo

In order to clone the public repository, type

git clone user@ferdinand.allmech.tuwien.ac.at:/home/tng/tng/SLangTNG_public.git my-project
cd my-project

Basic usage

Checking out and in

The history of own changes is obtained by

git log

Complete diffs:

git log -p

Overview of the change of ech step:

git log --stat --summary

The equivalent of cvs update which merges in any work that others might have done since the clone operation is:

git pull origin

If there are uncommitted changes in your working tree, commit them first before running git pull!!

The pull command knows where to get updates from because of certain configuration variables that were set by the first git-clone command.

You can update the shared repository with your changes by first committing your changes (see section "editing"), and then using the git-push command:

git push origin master

As long as the shared repository does not have any branches other than master, the parameter "master" can be neglected (else ALL other branches will be pushed/pulled as well)

Modifying and committing files

Add the updated contents of some files to the index:

git add file1 file2

You can see the planned changes by

git diff --cached

You can see all changes (which may not be part of the index) by

git diff

A brief summary is given by

git status

Commit all changes which have been passed to the index:

git commit

Commit and adding ALL tracked changes to the index in one flow (but without adding new files):

git commit -a

All changes being committed are merged into the local repository in the users' working directory. At times he should synchronize his clone with the main repository using the push and pull commands.

A notice on log messages: 1st line: max. 50 characters - short description. the other lines: long description. You can also pass log messages as command line paremeter via git commit -m "message"

Undoing a change

If you have changed a file by accident you can restore it from the master repo:

rm filename
git checkout filename

Using CVS

Please, use git directly and not the CVS emulator.

In order to set up your environment to commit using CVS, follow these steps:

Check out the repository (CVS version > 1.12.11)

cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co \<HEAD_name>

If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command, automatically saving it in your CVS/Root files, then you need to set them explicitly in your environment:
```
export CVSROOT=:ext:user@server:/var/git/project.git
export CVS_SERVER="git cvsserver"
```
For SSH clients that will make commits, make sure their server-side .ssh/environment files (or .bashrc, etc., according to their specific shell) export appropriate values for
- GIT_AUTHOR_NAME,
- GIT_AUTHOR_EMAIL,
- GIT_COMMITTER_NAME, and
- GIT_COMMITTER_EMAIL.
Clients should now be able to check out the project. Use the CVS module name to indicate what GIT head you want to check out. This also sets the name of your newly checked-out directory, unless you tell it otherwise with -d <dir_name>. For example, this checks out master branch to the project-master directory:
```
cvs co -d project-master master
```

Git