Very very basics of git

(to be updated as we go along, probably)

Disclaimer: I am no expert. I just started using git and everything described here may be flawed
and/or inefficient!

PART 0: Basics

Install git

Configure some basic things:

git config --global user.name <name>
git config --global user.email <email>
git config --system core.editor <editor-you-want-to-use>

PART 1: Getting started

Create a local repository:

git init --bare /path/to/repository
(e.g., /path/to/repository = /home/user/repositories/newGitRepo)
If a repository is to be shared across collaborators, it seems it is a good idea to create a bare
repository. Bare repositories contain hooks etc like svn repositories. No actual file can be
modified there. So accidental contamination with working copy can be easily avoided. Everyone
will have to clone the repository. It seems that “git push” will not work by default for non-bare
repositories. Still do not understand the concept of remote and remote add

Create first commit (import first files)

cd /path/to/work/dirs
git clone file:///path/to/repository repository-name
Use absolute path. If it does not exist, a directory with <repository-name> will be created.
(e.g., there will now be an empty directory in current working directory named "newGitRepo")

Copy/create first files

cd <repository-name>
cp /your/files .

Here it is a good idea to create a ".gitignore" file. Contents of this file will not version controlled.
Therefore add things like *.o, *.mod, *~. This file supports wildcard

Add all files (excluding the ones in .gitignore)

git add .
This is called staging. This step adds the file(s) to the list to be committed.

Commit the staged files

git commit / git commit -m "commit-message"
If you did not use -m, you will be asked to add a commit-message. Add a succinct, descriptive
commit message. Do not add a list of files, or lines of codes. Git will automatically track that.
(e.g., git commit -m "Initial file import.")

Push files to repository

git push origin master
This copies the changes to /path/to/repository

Now you have a non-empty repository. Start working.

When you start modifying the code:

1. Clone repository to your local working directory
git clone file:///path/to/repository
2. Go to your local working directory
cd <repository-name>
3. Edit your code.
4. When you are sure that you have confirmed some parts of the code, get ready to commit, i.e.,
stage
git add <files you want to commit>
You can selectively add some files. So if you are working three files, and you are sure about
your changes in file1 but not about file2 and file3, you can add only file1.
5. Commit files
git commit / git commit -m "commit-message"

6. Push files to repository

git push origin master

Note: You do not have to push every time you commit or stage. You can do that incrementally.
For example, you have three files, you are sure about change in file1, so you stage that and
commit that (no push). Then next time you change file3 and sure about the changes, so you add
and commit that. Now your local working directory is two commits ahead of the origin. If you
push now, the repository will advance by two increments. However, it is, I believe, a good idea
to always push after commits if you are collaborating with someone.

Use git status to check current status of your files, i.e., modified, staged, new, etc.
Use git diff to find differences between repository version and your local version of a file
Use git log to see the commit messages
Use git checkout -- <filename> to revert any local changes
Use git reset <file> to unstage a file before commit

If the repository has changed, and your local working copy has not, and you want to update your
local working copy from new repository files, use:
git pull

PART 2: Branching and Merging

Branching is a useful tool for collaborative code development. "master" is the default branch of a
repository, so when you are doing "git push origin master" you are updating master branch of
the repository.

CAUTION: The understanding of workflow is critical for efficient implementation of branching

and merging!

Example:
Clone the master first to your local directory
git clone ...
default git clone command always gets the master branch
In your working copy create a branch where you are going to develop new features.
git checkout -b newFeature
This will switch tracking to a new branch named newFeature

Do some modifications to files, and stage, commit, etc. This branch is only available to you, not
to other collaborator until you push it. The push command for this would now be
git push origin newFeature

At this point if your collaborators want to get this branch, they can do
git clone file:///path/to/repository --branch newFeature
--single-branch </path/to/destination/directory>

You can continue to work on this branch. Since usually collaborators will get the master branch,
they will not see the incremental changes you are making to your branch! They will only see
your pushed/published version.
The single-branch option came in git 1.7.10. With this option, you can clone only one single
branch, otherwise you can switch a branch even when you had originally cloned another
branch.

Once you are done developing and debugging, merge your branch to the master.
1. Change to master branch: git checkout master
2. Merge your branch to master branch: git merge --no-ff newFeature
Now this step may result in conflict, as someone else may have already updated the master. So
you need to go through every file where git will find conflict and manually change them. When
that is done, make sure you have all the new files staged. Then commit and push. Once you
push. you may or may not delete your branch.
--no-ff preserves history in greater detail.

CAUTION: I think this model is best suited if there are not many developers. If collaborators are
just users, this will work fine. If everyone is developing parts of code, something like the
proposed workflow (see below) may work better. Advantage of proposed workflow is that
collaborating developer not necessarily need to keep track of your incremental changes in your
feature. They only need to get when the feature is ready to be “released.”

PART 3: Proposed Workflow (NOT VERIFIED)

Proposed workflow:
http://nvie.com/posts/a-successful-git-branching-model/
Update master branch only when a feature is completely implemented and validated.
Create a branch for adding, developing, and debugging a feature.

To create an empty develop branch, do this at the beginning

git clone ...
git branch develop
git push -u origin develop

Collaboration pattern
John Mary

git clone ... git clone ...

git checkout -b j_branch git checkout -b m_branch

origin/develop origin/develop

EDIT file1, add fileJohn EDIT file1, add fileMary

git add . (local) git add . (local)

git commit (local) git commit (local)

git checkout develop (switches branch Edits more files

for merging)

git pull (updates local develop branch Does more local git commits
from repository)
 git merge --no-ff j_branch (merges Still working
j_branch to develop)
git branch -d j_branch (deletes local
j_branch)
git push (pushes the merged develop
branch back to repository)

Work completed Gets ready to merge her local commits to

develop branch

git checkout develop

This switche mary’s local branch to develop.
This will delete all local changes (while
keeping track of them). I think it may be safe
to keep a copy of local changes at this stage
and keep it until merge is completed.

git pull (update develop)

This will now contain John’s published merge

git merge --no-ff m_branch

This will now try to merge automatically. If
John and Mary worked on different files, this
is fine. If not, a conflict message will be
generated. In this example since both
modified file1, a conflict will be generated.
Now it is Mary’s duty to compare John’s
merged file1 and her current file1 and
manually create an updated merged file1.
Use git diff to see mary’s local and
develop’s published version.
Once the conflict is resolved:
git add file1
git commit and
git push
Now the repository contains both John’s and Mary’s branches all merged. It is a good idea to
use tag at this point.
git tag -a ## -m "Release: Added blah blah" master
git push --tags
NOTES

Before first use you must set name and email to be able to commit to a repository.

Useful commands:
$ git log --graph --abbrev-commit --pretty=oneline --color #nice
graphical display log
$ git add --all #adds all
$ git difftool -t vimdiff -y #use vimdiff to show difference
$ git merge --no-ff --no-commit

One way to set all this as aliases is to add following lines in $HOME/.gitconfig

–-
[user]
name = Your Name
email = email@domain.edu
[alias]
s = status
l = log --graph --abbrev-commit --pretty=oneline --color
a = add --all
vd = difftool -t vimdiff -y
mg = merge --no-ff --no-commit
[core]
editor = vim
–-

Nested branching is not natively possible, at least, by default.

git checkout -b newFeature develop
creates a new newFeature branch that points to the branch develop. If the last argument is
not specified, this new branch will point to the current HEAD, i.e., master by default. It
seems, to create an illusion of nested branch, we need this:
git checkout -b dev/newFeature develop
Here the actual name of the branch is dev/newFeature, it is not really nested. Also, if I
already have a branch develop, I can not create a branch develop/newFeature due to
some file system conflicts.

git remote show origin

shows the details of the origin
See here:
http://stackoverflow.com/questions/28790561/confused-about-creating-nested-branches-in-git
http://stackoverflow.com/questions/3161204/find-the-parent-branch-of-a-branch

Online resources

There are plenty:

https://www.atlassian.com/git/tutorials/setting-up-a-repository
http://nvie.com/posts/a-successful-git-branching-model/
http://rogerdudler.github.io/git-guide/

Retroactive tagging:
https://github.com/openmelody/melody/wiki/Devbest-tagging