Working with private repositories

in Athens Development servers

using git HOWTO
Version: 1.0
Date 09/07/2014
Author: Nikos Pelekanos

Introduction
The purpose of this document is to introduce software engineers to the use of
private repositories in Athens development servers using git. The document will go
through the repository creation, the repository cloning in a local repository for each
user account and also will demonstrate use cases, such as reviewing committed
code, committing new code, reverting commits, handling merge conflicts etc. As a
prerequisite, all the involved engineers should have a valid account in the following
Athens development machines:
caladan
10.158.67.81
hyperion
10.158.67.84
arrakis
10.158.67.85

What is git
Git is a version control system (VCS), but what is a version control system in first
place. Version control is a system that records changes to a file or set of files over
time so that you can recall specific versions later. A VCS allows you to: revert files
back to a previous state, revert the entire project back to a previous state, review
changes made over time, see who last modified something that might be causing a
problem, who introduced an issue and when, and more. Using a VCS also means
that if you screw things up or lose files, you can generally recover easily. Git was
designed and implemented by Linus Torvalds for Linux kernel development in 2005
and since then has become the most widely adopted VCS for software development.
More information about the history and the use of git can be found in [1], [2], [3].

Using git
The general use case scenario is about having a small development team that is
working on a project for which they would like to use a git repository. For clarity, we
are going to use an imaginary team, consisted from nikos, anna and george which
all have valid accounts to the Athens development servers.

Setup private git repository

First, someone from the team should create the shared git repository. For this in our
imaginary team, nikos is selected to create the repository in caladan development
server. nikos should start by creating a repositories directory in his home directory
and then another directory inside it called 1stProject.git. Moreover, the git init
command will create a bare repository:
nikos@caladan
$ cd /home/nikos
$ mkdir -p repositories/1stProject.git

$ cd repositories/1stProject.git
$ git init --bare --shared=group
# Initialized empty shared Git repository in repositories/1stProject.git/
$ ls
# config HEAD hooks objects refs
Now all developers in the team, should have read and write access to the shared
repository that nikos created since they all share the same group in Athens
development servers (hostingusers_cic_athens). Note that nikos must create a bare
repository every time a new project is to be added.

Git clone
nikos, anna and george should now clone the 1stProject shared repository from
where is located, ie repositories/1stProject.git in nikoss home directory. nikos
should use the following commands to clone the 1stProject repository in any of the
Athens development servers /scratch directory, for example /scratch directory in
hyperion is used below. Note all Athens development servers use the same home
directory per user, but different scratch directory.
nikos@hyperion
$ cd /scratch/nikos
$ mkdir 1stProject
$ cd 1stProject
$ git clone /home/nikos/nameOfProject.git .
# Clone messages
Since, this is an empty repository, nikos can commit the first file of the repository,
for example a README file.
nikos@hyperion
$ cd /scratch/nikos/1stProject
$ echo 1stProject README file > README
$ gia add README
$ git commit m Adding a README file
$ git push origin master
# Commit messages
$ git log
# commit b989d6e18f2b1e1ccf7614d6e76128071f8b20eb
# Author: Name=nikos <[email protected]>
# Date: Tue Jul 8 12:17:55 2014 +0300
#
# Adding a README file

Now anna and george can clone the 1stProject repository in their /scratch directory
in any Athens development server, for example:
anna@arrakis
$ cd /scratch/anna
$ mkdir 1stProject
$ cd 1stProject
$ git clone /home/nikos/nameOfProject.git .
# Clone messages
$ git log
# commit b989d6e18f2b1e1ccf7614d6e76128071f8b20eb
# Author: Name=nikos <[email protected]>
# Date: Tue Jul 8 12:17:55 2014 +0300
#
# Adding a README file
Now all team can work to the same shared repository through their local repository
in /scratch/$USER/1stProject directory.
Note that each user has created a local
repository and only by pushing/pulling commands, the shared repository
(/home/nikos/repositories/1stProject.git)
and
the
local
repository
(/scratch/nikos/1stProject) can remain in sync. More info about the push/pull
commands can be found below.

Reviewing repository
The command git log can be used to review the repository. The command has many
options (see git log --help) but the handiest are:
$ git log
$ git log --stat
$ git log p

#default output
#see affected files per commit
#see code differences per commit

Notice that each commit is accompanied by a hash value (for example

b989d6e18f2b1e1ccf7614d6e76128071f8b20eb). This can be used as an identifier
for the commit. For example, another handy command is git show commit-hashvalue, for example:
$ git show b989d6e18f2b1e1ccf7614d6e76128071f8b20eb
, will show the commit message, the modified files and the actual code differences.

Commit new changes and pushing them to the shared

repository
Changes in files can be committed first locally to the cloned repository and then can
be pushed towards the shared repository. For example if some changes are made
by nikos in README file, git status can be used to verify that there are uncommitted changes:

nikos@hyperion
$ cd /scratch/nikos
# make some changes in README file
$ git status
# On branch master
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
#
modified: README
#
no changes added to commit (use "git add" and/or "git commit -a")
git commit command can be used to commit the changes to commit the README
file changes in nikos local repository.
$ git commit m more changes in README file README
git status will now report that there are no uncommitted changes:
$ git status
# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
nothing to commit (working directory clean)
If nikos wants to push the changes in the shared repository, git push command
should be used:
$ git push origin master
If new files are needed to be added in the repository, the git add command should
be used prior to the git commit command:
$
$
$
$

touch newFile
# create a new file
git add newFile
# add the new file in the local repo
git commit m new file newFile commited # commit the new file in the local repo
git push origin master
# push the change in the shared repo

Reviewing uncommitted changes

git diff command can be used to see the changes made to files that have not yet
been committed to the local repository:

$ git diff

Pulling changes from shared repository to local repository

If a user wants to update his local repository with the latest changes in the shared
repository, git pull command should be used:
$ git pull origin master
The pull commands will synchronize all the changes that were pushed to the shared
repository from the other users, between the time of the last sync (last pull
command) and now.

Conflicts during push/pull commands

Since one or more team members can write in the same area of a file on the same
time, merge conflicts can arise while pushing/pulling towards/from the shared
repository. In this case similar messages to the following will appear:
$ git pull origin master
# remote: Counting objects: 12, done.
# remote: Compressing objects: 100% (5/5), done.
# remote: Total 8 (delta 0), reused 0 (delta 0)
# Unpacking objects: 100% (8/8), done.
# From /home/pelekano/repositories/1stProject
# * branch
master
-> FETCH_HEAD
# Auto-merging README
# CONFLICT (content): Merge conflict in README
# Automatic merge failed; fix conflicts and then commit the result.
In this unfortunate case, manual work is needed to resolve the conflict. The user
that encountered the conflict should modify the README file in a way that the
development process will move forward and then it should (resolve the conflict):
$ git add README
$ git commit a
, and when finished, it can synchronize the changed to the shared repository using
the git push command:
$ git push origin master

Reverting commits
In an unfortunate case that some commit should be reverted, git revert commit can
be used:

$ git revert b989d6e18f2b1e1ccf7614d6e76128071f8b20eb

The above command reverts a certain commit indicated by the git hash value. This
will result in a new git commit with the exact opposite changes as the commit that
needs to be reverted. git push should be used to update the shared repository.

Conclusion
This document described a very limited set of capabilities that git has. An
interested user can go through [1] for more git capabilities and use cases (such as
branching, staging, stashing).

References
[1].
[2].
[3].

Pro git book

Git Wikipedia
Git cheat sheet