GIT - Commands & HowTo's

Stuff that is common to both types of requests :

merge request (aka MR) :

pull request (aka PR) :

Ask Git to cache your credentials :

git config --global credential.helper cache

If the default 15 minutes aren't enough :

git config --global credential.helper "cache --timeout=3600"

1. Read this tutorial
2. Test SSH connection to GitHub :
   • ssh -T git@github.com
   • ssh -i ~/.ssh/github -T git@github.com
3. Append to ~/.ssh/config :

   Host github.com
   	User		git				not an example, this MUST be "git"
   	IdentityFile	/home/stuart/.ssh/github

4. Then, you can create a new repository and store it on GitHub

Let's try this :

#!/usr/bin/env bash

workDir=$(mktemp --tmpdir -d tempDir_XXXXXXXX)
zerosFile="$workDir/zeros"
otherFile="$workDir/other"

getDirSize() {
	directory=$1
	message=$2
	echo -en "\t==>\tDirectory size [$message] : "
	du -sh $1
	}

countOccurrencesInGitLog() {
	fullPathToFile=$1
	trackedFile=$(basename "$1")
	echo -en "\t==>\tNUMBER OF OCCURRENCES OF '$trackedFile' IN 'git log' : "
	git log --name-status | grep -c "$trackedFile"
	}

# init
cd "$workDir"
git init
getDirSize "$workDir" 'Empty Git repository'

# create and commit "$otherFile"
echo 'this is an other file' > "$otherFile"
git a "$otherFile"
git co -m 'this is an other file'
getDirSize "$workDir" "After creating + committing the 'other' file"

# create and commit "$zerosFile"
dd if=/dev/zero bs=1K count=100 of="$zerosFile"

getDirSize "$workDir" "'zeros' file created but not committed yet"
git a "$zerosFile"
git co -m 'Lots of zeros !!! (initial commit)'
getDirSize "$workDir" "'zeros' file committed"

# append data to "$zerosFile" + commit
for i in {1..5}; do
	echo "hello world ($i)" >> "$zerosFile"
	git a "$zerosFile"
	git co -m "hello world ($i)"
	getDirSize "$workDir" "After hello world ($i) in 'zeros' file"
done

# cleaning the git repo
git gc
getDirSize "$workDir" "After 'git gc' (1)"

# untracking "$zerosFile"
git rm --cached "$zerosFile"
git co -m "rm --cached 'zeros'"
getDirSize "$workDir" "After untracking the 'zeros' file + commit"

# what about the git log (1) ?
countOccurrencesInGitLog "$zerosFile"

# cleaning the git repo
git gc
getDirSize "$workDir" "After 'git gc' (2)"

# removing the 'zeros' file
rm "$zerosFile"
getDirSize "$workDir" "After 'rm' of 'zeros' file"

# cleaning the git repo
git gc
getDirSize "$workDir" "After 'git gc' (3)"

# what about the git log (2) ?
countOccurrencesInGitLog "$zerosFile"

# cleaning before leaving
cd ..
[ -d "$workDir" ] && rm -rf "$workDir"

Initialized empty Git repository in /tmp/tempDir_FWkkVbkH/.git/
	==>	Directory size [Empty Git repository] : 35K	/tmp/tempDir_FWkkVbkH
[master (root-commit) 599b54f] this is an other file
 1 file changed, 1 insertion(+)
 create mode 100644 other
	==>	Directory size [After creating + committing the 'other' file] : 50K	/tmp/tempDir_FWkkVbkH
100+0 records in
100+0 records out
102400 bytes (102 kB, 100 KiB) copied, 0.000523495 s, 196 MB/s
	==>	Directory size ['zeros' file created but not committed yet] : 150K	/tmp/tempDir_FWkkVbkH
[master daa0106] Lots of zeros !!! (initial commit)
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 zeros
	==>	Directory size ['zeros' file committed] : 155K	/tmp/tempDir_FWkkVbkH
[master bc46b8c] hello world (1)
 1 file changed, 0 insertions(+), 0 deletions(-)
	==>	Directory size [After hello world (1) in 'zeros' file] : 162K	/tmp/tempDir_FWkkVbkH
[master 8ceab4f] hello world (2)
 1 file changed, 0 insertions(+), 0 deletions(-)
	==>	Directory size [After hello world (2) in 'zeros' file] : 168K	/tmp/tempDir_FWkkVbkH
[master d35a527] hello world (3)
 1 file changed, 0 insertions(+), 0 deletions(-)
	==>	Directory size [After hello world (3) in 'zeros' file] : 174K	/tmp/tempDir_FWkkVbkH
[master 7db7977] hello world (4)
 1 file changed, 0 insertions(+), 0 deletions(-)
	==>	Directory size [After hello world (4) in 'zeros' file] : 182K	/tmp/tempDir_FWkkVbkH
[master 6cd929a] hello world (5)
 1 file changed, 0 insertions(+), 0 deletions(-)
	==>	Directory size [After hello world (5) in 'zeros' file] : 188K	/tmp/tempDir_FWkkVbkH
Counting objects: 21, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (19/19), done.
Writing objects: 100% (21/21), done.
Total 21 (delta 6), reused 0 (delta 0)
	==>	Directory size [After 'git gc' (1)] : 153K	/tmp/tempDir_FWkkVbkH
rm 'zeros'
[master d68e9bd] rm --cached 'zeros'
 1 file changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 zeros
	==>	Directory size [After untracking the 'zeros' file + commit] : 156K	/tmp/tempDir_FWkkVbkH
	==>	NUMBER OF OCCURRENCES OF 'zeros' IN 'git log' : 9
Counting objects: 22, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (14/14), done.
Writing objects: 100% (22/22), done.
Total 22 (delta 6), reused 21 (delta 6)
	==>	Directory size [After 'git gc' (2)] : 154K	/tmp/tempDir_FWkkVbkH
	==>	Directory size [After 'rm' of 'zeros' file] : 53K	/tmp/tempDir_FWkkVbkH
Counting objects: 22, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (14/14), done.
Writing objects: 100% (22/22), done.
Total 22 (delta 6), reused 22 (delta 6)
	==>	Directory size [After 'git gc' (3)] : 53K	/tmp/tempDir_FWkkVbkH
	==>	NUMBER OF OCCURRENCES OF 'zeros' IN 'git log' : 9

What we can remember from this experience :

• A fast-forward is one method to execute a merge :
  • either when explicitly running git merge
  • or implicitly with a git pull = git fetch + git merge FETCH_HEAD
• available methods to proceed to a merge include (details) :
  • forcing a fast-forward
  • forbidding a fast-forward
  • going best-effort to do a fast-forward and abort if it's not possible
• git merge goes fast-forward when a branch can be advanced along a linear sequence. This happens whenever you pull changes that build directly on top of the same commit you have as your most recent commit. In other words, there was never any divergence or simultaneous commits created in parallel in multiple repositories. If there had been parallel commits, then git merge would actually introduce a new merge commit to tie the two commits together.
• When a non-fast-forward merge occurs, there is always the possibility that a conflict occurs. In this case, git merge will leave conflict markers in the files and instruct you to resolve the conflicts. When you are finished, you would issue a git commit -a to create the merge commit.

Increasing permissions :

Setting permission bits individually :

Conclusion

• are scripts that Git executes before or after events such as: commit, push, and receive
• are a Git built-in feature : nothing to download / install
• are run locally
• appear as scripts found in .git/hooks

Available hooks (source) :

Hook execution fails on fatal: not a git repository: '.' (source) :

OLD_GIT_DIR=$GIT_DIR
unset GIT_DIR

(part of the script where taking actions on a repo occur)

GIT_DIR=$OLD_GIT_DIR

In order to find out, let's build a repo and commit some stuff :

testDir='/tmp/test'; testFile='test.txt'; mkdir -p "$testDir"; cd "$testDir"; git init; echo 'hello world' > "$testFile"; git add "$testFile"; git commit -m 'Hello to the world.'; echo 'hello everybody' >> "$testFile"; git add "$testFile"; git commit -m 'Hello to people.'; git show

Here's our 2^nd commit, git show returns :

commit 93ce9bef143d57b6c0133d659db0c3030c24f75f
Author: Thomas ANDERSON <thomas.anderson@metacortex.com>
Date:	Mon Dec 15 17:54:22 2014 +0100

	Hello to people.

So, how is generated this commit ID : 93ce9bef143d57b6c0133d659db0c3030c24f75f ?
Try this :

(printf "commit %s\0" $(git cat-file commit HEAD | wc -c); git cat-file commit HEAD) | sha1sum

This should output the exact commit ID we're talking about : 93ce9bef143d57b6c0133d659db0c3030c24f75f

More details :

Fine, but why is this important ?

• MUST-READ for beginners : Getting Started - Git Basics
• Some basic Git vocabulary
• For those who need sketches to get things :
  • start with this one : A Visual Git Reference
  • animates as you type : Visualizing Git Concepts with D3
  • the all-in-one : The Git cheatsheet
  • Rachel M. Carmena has great sketches to teach Git.
• Documentations I wrote about Git :
  • A training session I made for colleagues (in french) : Git - Présentation basique et non-exhaustive
  • My humble Git tutorial
• The Git FAQ
• Git high-level porcelain commands

"regular" repositories :

bare repositories :

How to convert a "regular" repository into a bare repository ?

git clone git@github.com:/everzet/capifony.git

Cloning into 'capifony'...
ssh: connect to host github.com port 22: Connection timed out
fatal: The remote end hung up unexpectedly

git clone git://github.com/everzet/capifony.git

Cloning into 'capifony'...
fatal: unable to connect to github.com:
github.com[0: 204.232.175.90]: errno=Connexion terminée par expiration du délai d'attente

git clone https://github.com/ehashman/ansiblefest.git

Cloning into 'ansiblefest'...
fatal: unable to access 'https://github.com/ehashman/ansiblefest.git/': Failed to connect to 10.2.0.20 port 3128: Connection timed out

This is a special case because :

• I already did the proxy configuration described below
• this was on an old VM, and 10.2.0.20 isn't the proxy to use anymore

1. define the http_proxy environment variable :

   http_proxy=http://user:password@host:port

2. make Git aware of it :
   • git config --global http.proxy $http_proxy
   • OR add into ~/.gitconfig :

     [http]
     	proxy = http://user:password@host:port

3. clone via HTTP : git clone http://github.com/everzet/capifony.git
4. do the same for https

bare

Git bare repositories

FETCH_HEAD

several definitions until I find one that summarizes them all

• the SHAs of branch/remote heads that were updated during the last git fetch (source)
• a short-lived reference (i.e. a pointer) to keep track of what has just been fetched from the remote repository by git fetch (source)
• FETCH_HEAD records the branch which you fetched from a remote repository with your last git fetch invocation (source)

feature branch

TODO:

fork

TODO:

GIT_AUTHOR_DATE, GIT_COMMITTER_DATE

Without surprise, both are dates handled by Git (), and the difference lies in the difference between an author and a committer :

author

the person who wrote the code

committer

the person who committed the code on behalf of the author (and who is often the author himself)

This is important because Git allows rewriting history, or applying patches on behalf of another person, which is what is done by a maintainer with code written by a contributor on an open source project.

HEAD

• HEAD is the commit on top of which git commit would make a new one. (details)
• Refers to a named branch, which in turn refers to a commit (a branch is updated after each commit to point to the latest commit).
• HEAD is often considered as the latest commit of the current branch, which is partially true since HEAD can actually point to any commit. In such case (pointing to a specific commit instead of pointing to a named branch), we would be in detached HEAD mode (details 1, 2).

head

• a reference to a commit object (i.e. a commit ID)
• Each head has a name (branch name, tag name, ...). By default, there is a head in every repository called master.
• A repository can contain any number of heads.
• At any given time, one head is selected as "the current head". This one is aliased to HEAD (always in capitals).
• References, heads or branches can be considered like post-it notes stuck onto commits in the commit history. Usually they point to the tip of series of commits, but they can be moved around with Git commands (checkout, revert, ...)

index (aka "cache" or "staging area")

This is where you place files before committing them into the Git repository. You can imagine it works like this :

• the working area is the plant floor were your product is manufactured
• the index is the "packaging / shipping" floor : this is where you bring the product itself, some accessories and shipment documents. You pack everything in a box and ship the whole package.
• well, now, "shipping" is actually what is made with a commit

Adding file(s) to the index is made with git add.

The index is a binary file, usually found at .git/index.

reflog

Reference logs (aka reflogs) :

• the history of HEAD values
• record when the tips of branches and other references were updated in the local repository
• are useful in various Git commands to specify the old value of a reference. For example :
  • HEAD@{2} means where HEAD used to be two moves ago
  • master@{one.week.ago} means where master used to point to one week ago in this local repository
  (details)

remote

Any Git repository you "synchronize" yours with, via push / pull commands. This is typically a GitLab or GitHub repository.

remote-tracking branch (sources : 1, 2)

• a remote-tracking branch is a local branch that represents a remote branch
• the label of a remote-tracking branch (i.e. what it points to) is updated only with network operations such as clone, fetch, pull and push
• remote-tracking branches are automatically created on repositories started with git clone. When manually linking a local and a remote repository with git remote add, you'll have to explicitly declare remote-tracking branch(es)
• How to track a remote branch ?

upstream

Due of the decentralized nature of Git, all repositories are born equal, and none has a central or server role more than any other. However, developers teams need some kind of central point to act as a reference for the whole team. This central repository is called the upstream repository, it is typically the one developers interact with via GitLab.

Being an upstream repository is more an organization role than a technical functionality.

upstream branch

Checking out a local branch from a remote-tracking branch automatically creates what is called a tracking branch (and the branch it tracks is called an upstream branch). There are several ways to associate a local branch with a remote branch.

What's the point of defining an upstream branch ?

Adding a remote tracking branch means that Git then knows what you want to do the next time you'll git fetch, git pull or git push. It assumes that you want to keep the local branch and the remote branch it is tracking in sync and does the appropriate thing to achieve this. (source)

working tree (aka "working copy")

These are the files you're working on and that are tracked by Git.