Remember, the text presented here targets a single developer setup (as the first part did). I intend to do a distributed git setup in the third installment.

Note : Few commands have been broken into two or more lines to fit into the blog’s layout.

Let’s begin!

Command 1 : Time Travel: Moving back and forth between revisions.

The whole point of a version control system is to maintain revision history of your source code. And permitting you to view, how your code looked, at any point of time in the recorded history.

Git records your revisions in the form of commits. Every commit is assigned a unique hash to identify it. (Git uses SHA1 hashes). You can view the commit hash by issuing the git-log command (Check part one). The hash is displayed as a hexadecimal string on the line beginning with the word “commit” in the log.

Now that we know all this technical mumbo-jumbo, let’s use it to do some real work.

Move to a commit in the past.

To move to a particular commit back in time we use the command git-checkout, introduced in part-I for moving between branches. The syntax is similar, but instead of the branch name we use the commit hash. Always make sure you commit any changes or stash them (see next command) before you issue the checkout command; Else the changes will move across!

here’s the syntax:

$ git checkout commit_hash

Let’s see an example.

First I issue the git-log command to find the hash of a commit I want to switch to.

$ git log
commit 1ef801f70a99b07bb578bac4a3c2edb52b367e1d
Author: xk0der <amit .. AT .. xkoder .. com>
Date:   Fri Jun 5 12:52:16 2009 +0530

Added few comments

commit ccbaeec43300f19dd04308b6c62a3f03f6233725
Author: xk0der <amit .. AT .. xkoder .. com>
Date:   Fri Jun 5 12:51:30 2009 +0530

Initial import

(email address obfuscated for spam bots)

As you can see, I have just two commits here. I want to move to the commit with the log message “Initial import” i.e. my first commit. So I issue the following command.

$ git checkout ccbaeec4

as you can see I just typed in the first 8 characters of the hash. That is the minimum that Git requires to successfully identify the commits uniquely. You may supply more than eight characters or the full hash if you wish.

After the checkout is complete, you can view your files to see how they looked in the past . If you want to modify your files and want to propagate the changes to the master’s HEAD, check command 6 below.

Moving back to the present
To go back to the master’s HEAD; which is the present state of your code; issue the command:

$ git checkout master

As I’ve said earlier, always remember to commit changes or stash them before moving between branches or commits.

Command 2: git-stash – Moving without committing.

This is one handy command you’ll find very useful. It lets you store your current changes to a temporary location. These stashed changes can then be recalled back when required. Thus alleviating the need to commit every time you need to move across branches or commits.

Stashing changes
the syntax is:

$ git stash

When issued, all changes will be stashed to a temporary location and you will have a clean current HEAD. You can verify this by issuing the git-status command.

When done with your other work, you can pop back the stashed changes by issuing the following command.

$ git stash pop

Pretty cool ‘eh! But when to use it?

When to use git-stash; Here is a one typical scenario
Suppose you are working on one of the feature branch and you get a mail that something is not fine with the code on your trunk, the ‘master branch‘. Now one way to to fix something on the master branch is to:

• First commit changes on the ‘feature’ branch.
• Next, checkout the master branch and fix what’s required.
• Commit changes to master.
• Checkout the ‘feature’ branch.

But, what if, you do not want to commit the changes on the ‘feature’ branch? Probably because you are halfway through something, or you want to test your code before you commit it. You you stash all changes as shown below.

$ git stash
$ git checkout master
...Fix some stuff...
$ git commit -a -m "Bug:12 fixed - thread no longer dies prematurely"
$ git checkout feature
$ git stash pop
...Continue working normally...

Multiple stashes
You can stash more than one set of changes, if required, by issuing the git-stash command multiple times.

When you use the `git-stash pop` command, the latest stash comes out first, much like a stack.

Viewing stored stashes

To view a list of stashed changes issue the following command

$ git stash list

There are more fancy things, that you can do with this command (checkout the man pages for git-stash). But for normal daily use the first two commands will suffice.

Command 3: git-diff – some switches to differentiate better.

I’ve already explained this command in the first part. Here I’ll discuss some command line options that you can supply, to help find the right information.

Finding which files differ (instead of what differs inside files)

Here’s the command:

$ git diff --name-status

This will list the files that have been modified(M), added(A) or deleted(D) with respect to the current HEAD and uncommitted changes, if any. You may supply commit hash(es) to find difference between those two commits.

$ git diff --name-status hash_1 hash_2

Using the HEAD symbol

You can use the HEAD symbol to view diff’s between the current HEAD and previous revisions, as follows:

$ git diff HEAD~1

This command will show you the diff between current HEAD and the immediate previous commit. This command is a shortcut for

$ git diff commit_hash_for_HEAD
  commit_hash_just_before_HEAD

What is the HEAD?

If you remember, as discussed in part one of this tutorial, HEAD refers to the latest commit on the current branch. 

You can change the number after the tilde (~) to find differences between HEAD and ‘that’ many commits before the HEAD commit. experiment and see what you find. This is a totally safe command to play with

Command 4 : git-add revisited.

In part one of this tutorial we learned how to make git keep track of a file or number of files by issuing the git-add command. Well that is one work git-add does. Let’s find out what’s the other thing git-add is used for.

Before that, let’s see how we have been committing changes up till now.

$ git commit -a -m "Commit Message"

We know that the -m switch is to specify the commit message, what is that -a switch doing there?

Before I explain; The above command is (almost) equivalent to the following two commands, in sequence:

$ git add .
$ git commit -m "Commit Message"

So you see, that little -a switch is actually a shortcut to add all files. But haven’t we already added the files for git, to keep track of?

Yes we have but git also wants you to tell it Which files to commit; and this is what the first ‘git add .‘ command is doing. It is telling git to add all new, modified or deleted files to the ‘commit stage‘. So after the files have be staged for committing, we actually commit i.e. register our changes, by issuing the second command (git-commit).

One small but important quirk.
As I said the command is almost equivalent to the latter sequence; so what’s the catch?

The switch -a with git-commit DOES NOT ADD files that are not currently being tracked by git.
WHEREAS; ‘git add .‘ adds files not being tracked by git for commit as well.

Why to use git-add this way? Read ahead.

Committing only selected files

Suppose you are working on, say 3 source files. You realize that you are pretty much content with the changes you have made to two of the files but the third file is still work in progress. You can commit just these two files by issuing the following commands:

$ git add path/to/file1
$ git add path/to/file2
$ git commit -m "Some feature done"

When you are done with the third file; You can commit changes by either issuing the following commands

$ git add path/to/file3
$ git commit -m "Third feature done"

OR, by issuing the following command (Since we want to commit all modified files.)

$ git commit -a -m "Third feature done"

You can use ‘*’ and ‘?’ wild-cards to stage multiple files for commit with the git-add command.

example:

$ git add header/*

This command will add all files inside the folder “header” to the ‘commit stage’.

Remember: git-add just stages the changes for commit (i.e tells git which files to commit), the actual commit i.e. write to the repository happens when you issue the git-commit command.

Also checkout the git-reset command listed below; to learn, how to remove files from ‘commit stage’.

Command 5 : git-rm ; Few more things you should know.

The –cached switch:

When git-rm is used with this switch the file are removed from git’s repository but are no deleted from the disk.

Example:

$ git rm --cached
  path/to/file/or/folder

The above command will remove the particular file or folder but they will continue to exist on the disk. If you issue git-status command the file will be shown as deleted, as well as un-tracked.

git-rm without the –cached switch:

When used without the - -cached switch git-rm removes the file from the repository as well as from the disk.

You need to commit changes after using the git-rm command with or without the - -cached switch.

All isn’t lost!

Remember that the file(s) that you removed with git-rm and then commit changes, only apply to that commit. All your previous revisions will still have the removed file(s) or removed folder(s). So if you checkout previous revisions you can get the files or folder back.

You cannot alter the commit history(well! see git-reset below), as that goes against the version control system’s primary functionality; which is to preserve history of changes to the source code repository.

Command 6 : Managing branches.

We already know how to create, delete and move between branches. Here are a few more commands to help you manage your branches.

Creating a branch out of some older commit.

Suppose you want to move back to a particular commit and create a branch out of it. You can issue the following commands

$ git checkout commit_hash
$ git branch branch_name
$ git checkout branch_name

A convenient shortcut for the above command-set is:

$ git checkout
  -b branch_name commit_hash

The above command is exactly equivalent to the three commands listed before.

An example with the shortcut command:

$ git checkout
  -b bugfix_branch HEAD~2

The above command will create a branch named bugfix_branch which will be positioned at two commits bellow the current HEAD.

You can use the gitk gui to visually checkout the branches. Try it, it’s really cool! (Checkout the part one of this tutorial to know more about gitk).

Command 7 : git reset command

Clearing changes
You made some changes to your source code and realize you don’t need those changes. Maybe you were just testing something. What to do now?

Just use the following command to clear any changes and move back to the latest clean state, i.e. the last commit.

$ git reset –hard

BE VERY CAUTIOUS while issuing this command as it is IRREVERSIBLE.

This command will clear all un-committed changes and revert back all your files to the state reflected by your last commit.

The above command can be quiet useful if you do a merge between branches or from other people repository and get some conflicts; and you want to restore your repository back to the clean state. Just issue this command you’ll be back to the un-merged state.

Clearing files staged for commit
After adding files to the ‘commit stage’ you realize you do not want to commit those files. You can issue the following command to un-stage them.

$ git reset

This command un-stages files staged for commits ONLY, so all your changes are still there.

Deleting commits!

This command is provided for those rare cases where you REALLY REALLY DO need to ‘alter’ the history. Or for those occasional cases where you did some bad commits.

Issue the following command to delete a commit forever and ever.

$ git reset –hard HEAD~2

This command gets rid of the last two commits; kind of rewinds back to the third last commit.

If you have shared your repository, you are strongly discouraged to use this command. But as a single developer you can use it if really required.

Command 8: Garbage collection; Compress your repo and get some free space.

I’ve saved the simplest command for the end! Smile now

Issue the following command to make git compress your repository and clean it up.

$ git gc

This operation might take some time, a couple of minutes or so.

When finished, you’ll probably have more disk space

You should gc once is a while.

gc = garbage collection.

Yeah, that’s it! Just eight commands, but I’ve got two more things to make life easier for git users. So it adds up to ten right!

Extra 1 : Ignore some files; .gitignore explained.

Not all files inside your project folder are required to be tracked by git. Some example include: object files, swap files etc.

Create a file name ‘.gitignore‘ in the base folder of your git repository and put in the name of files inside ‘.gitignore‘ as explained below, to make git ignore them.

Simple wild-cards are recognized.
‘*‘ and ‘?‘ wild-cards plus regular expression’s square bracket `[ ]‘ notation is recognized.

So, for example, if you want to ignore all files ending with the extension ‘bak‘ you can specify the following in your .gitignore file.

*.bak

The above line, if present, in your .gitignore files will ignore all files ending with ‘.bak’ anywhere inside the project folders.

Ignoring a particular file or folder using absolute path notation.

Suppose you have the following directory structure for your project, where “Project” is the base directory of your project’s repository.

Project
    |-- .gitignore
    |
    |-- .git
    |
    +-- Folder_1
    |
    +-- Folder_2
    |       |
    |       \--- Folder_3
    |
    \-- Folder_4
            |
            +--- File_1
            +--- File_2
            +--- File_3

Now suppose you want to ignore the folder `Folder_3‘ put following in your .gitignore file:

/folder_2/folder_3/

Notice the forward slashes at the beginning and at the end:

• If you remove the preceding forward slash, git will ignore all folders named ‘folder_3‘ inside any folder named folder_2.
• Removing the forward slash at the end will make git treat the name ‘folder_3‘ as a file name instead of a folder. So in case if we had a file named ‘folder_3‘ inside folder_2, that would be ignored.

Now, if you wanted to ignore the file File_2 as shown in the diagram above, you place the following in your .gitignore file:

/folder_4/file_2

Notice we did not put a forward slash at the end, if we had, git will treat the name ‘file_2‘ as a folder name.

So here are the rules, re-iterated.

1. Absolute paths begin with a forward slash ‘/’.
2. Folders names should always be suffixed with a forward slash ‘/’.
3. File names should NEVER be suffixed with a forward slash ‘/’.

The use of square brackets as shown in the example below. They work very much like regular expression notation.

An example .gitignore file.

# git ignore file
# comments start with hash

# ignore all object files, all
# files ending either with '.o' or '.a'
*.[oa]

# Ignore all files with
# the extension *.swp
*.swp

# Ignore a single file
/folderA/folderB/build.info

# Ignore a folder named
# temporary in the base folder.
/temporary/

# Ignore folders named _object
#  anywhere inside the project.
_object/

What’s the use of .gitignore, after all?

Well, if still haven’t figured out let’s look at a typical coding scenario.

You have your project, added all files to your .git repository, and did and initial commit. Now you start editing some files, your favorite editor creates some backup files ending with ‘.bak’ extension.

Now you do git-status to check what all files changed, git tell you which files have been changed but also lists a the ‘.bak’ files as being untracked.

After few days, the list of untracked files becomes so long, that doing git-status scrolls past your screen. Not pretty right!

Also, you cannot do ‘git add .’ to stage files for commit, as this command will add the ‘.bak’ files to be committed as well, unnecessary bloating your repository.

What’s the solution? Just create a .gitignore file inside your project’s base directory and place a line containing ‘*.bak’ in it. Now do git-status; wow! neat ‘eh.

Extra 2 : Throw in some colors and introduces yourself to git.

Your name and email address in commits
Edit the file .git/config inside your base folder (project folder) and enter the following lines.

[user]
    name = Your Name
    email = your email Id

example:

[user]
    name = xk0der
    email = amit@xkoder.com

After placing these details in your file, the next time you commit any changes, your name and email id will be registered as the author of that commit.

Colorizing git’s output.

Gary has a small and simple post on how to get color’s in git’s output here:

http://scie.nti.st/2007/5/2/colors-in-git

That’s it! Go do some Git-fu.

In the next installment I intend to cover distributed git setup and few more commands. Till then enjoy!

Git is marvellous piece of tool every programmer must have. Git is a distributed version control system developed by Linus and others. Yes you guessed it, it is used heavily by the Linux (kernel) developers apart from many other projects.

How will Git help you and what this post covers.

Scope of this post : This post will deal with the usage of Git by an individual developer only.

Why use version control : Version control gives you a great deal of flexibility while coding. You can make changes without having to worry about breaking things, as you can always move back to previous version(s) of your code. Version control also allows you to compare changes as you move ahead, helping in bug-fixing apart from other benefits.

Why use Git : There are a number of other version control systems available, some centralized systems some distributed systems. Amongst them, Git is one of the fastest version control system, very simple and easy to use, and has lot of helpful features packed in very a small package. Check my other post to know more reasons.

Prerequisite

1) You need a computer with preferably Linux (any flavor) installed on it. (This post does not deal with Windows, though you may use the commands given here without any modifications (probably!)).

2) You need Git.

on Fedora distribution, you may install git using the following command

$ sudo yum install git

On Ubuntu distribution, you may install git using the following command

$ sudo apt-get install git
$ sudo apt-get install git-core

(Edit: 21/Oct/2008 – Thanks to robo47 for pointing out the mistake)

For other methods and building from source check out this page.

3) You need some project which you are developing (or would be developing) . The project’s language could be anything .. C, C++, D, Python, Perl, HTML, JavaScript, plain text files … you got the idea right?

Let the show begin

Command 1 : Initializing an empty git repository.

Befor you can start using the power of git you need to create an empty repository and tell git which files to track. The first command that I’m presenting initializes an empty git repository.

Before executing the command you need to be at base folder of you project. For example if you have all the source code for you project stored here /home/xk0der/SourceCode/myProject, (We’ll call this folder as the base folder for ease of discussion), move there first. Now execute the following command once you are in the base folder.

$ git init

This will create an empty repository in the current directory (the base folder).

For every project that you want to track using git, go to its base folder and issue this command first and then the next 2 commands presented below.

Command 2 : Adding files to git repository.

The next step is to add files to your git repository, essentially telling git that these are the files we want to keep track of. Execute the following command from the base folder.

$ git add .

This will add all the files from the current folder and sub-folders recursively to the git repository.

Command 3 : The commit command.

This is one command you’ll be using quite often.

the above command adds the files but does not commit the changes to the git repository. So you need to issue the following command to make the changes final.

$ git commit -a

This will open a text editor (probably vi) where you can add some comments about this commit. If you prefer not to use the text editor, you can specify the commit message from the command line it self, just use the following format instead of the above one.

$ git commit -a -m "Initial import"

The -m switch is used to specify the commit message. In our case the commit message is “Initial import”. You can put anything between the quotes for your message.

You are ‘all’ ready!

Now open your favorite text editor and start coding. When you feel you have accomplished something or you just want to save the current state of your source code issue the git-commit command as described above. The commit command will create a new checkpoint and save the current status of your source code.

Git (like any other version control system) saves all the commits you have done to your source code repository. This enables you to go back and forth between commits and inspect the changes.

Now let’s move forward and learn a few more commands.

Command 4 : Viewing the commit log.

You can view all the commits you have done till now using the following command

$ git log

This command shows the commit history with the

1) Unique commit hash
2) Name and email of the person who performed the commit
3) Date and time of commit
4) The commit message

Of all these, the first item, the unique commit identifier, the SHA1 hash is of importance to us. This hash will be used with some of the commands listed next, and is used with a plethora of other git commands, not listed here

Command 5 : Checking the current status.

While coding, you may want to see what all files have changed, before you do a commit to store them in the git repository. This command helps you achieve that.

$ git status

The above command will list all files that have changed since your last commit.

Command 6 : Finding the difference between commits.

Apart from just viewing files that have changed, you may be interested in viewing the actual differences in the source code.

$ git diff

The above command will show a difference ( a diff ) with respect to your last commit and current changes.

The diff command can actually be used to compare difference between any commits

To view difference between a previous commit and current changes.

$ git diff commit_hash

here the commit_hash is the first eight characters (hex digits) of commit hash as shown in the commit log by the git-log command. Yes! you need not specify the full hash, just the first eight digits are good enough.

To view differences between two previous commits.

$ git diff commit_hash_1 commit_hash_2

This command will display differences between the two commits identified by the commit_hash_1 and commit_hash_2.

Command 7 : Creating branches!

Don’t be scared by the word “branching”, specially if you never dealt with them. Branches are easy to play with and are very useful.

Before I show you the command a bit more discussion about branches.

• You can view branches as being diversion from the main linear commit tree.
• All branches stem out from the master branch, the name given to the main trunk.
• Every branch has it’s own commit log.
• You can have different code in same files across difference branches. (This is the main feature of branching). Actually git goes even further and allows you to have not only different content in files across branches but even different sets of files across different branches.
• At one point of time, you can be sitting only on one branch. What this means is that, the source code from the current branch will be the effective one, the one to which you would be making changes.

Why use branches?

Suppose you have an almost stable source code and you are to release the product in a month or in a week or two. You also have plans to include another great feature into your code, but are afraid it might break your code and your release plans may go hay-wire.

This is where branches come into picture. Just create an experimental branch from you main stable trunk ( the one you’ve been working on up till now is the main trunk, the master branch). After you have created the experimental branch, you can continue fixing bugs and polishing the code on the main, i.e. the master branch. Meanwhile you can also continue working on the experimental branch without affecting a line of code on the master branch.

In the end, if you find that the experimental feature is working good enough, merge it into the master branch and release your product. If the experimental feature didn’t quite work out, you can still release the product from the master branch. The experimental branch is still there so you can continue working on it till it gets stable.

This is one scenario (and the most often reason, though not the only one), to create branches.

Okay now, back to commands . Issue the following command when you want to create a branch.

Creating a branch

$ git branch branch_name

branch_name could be anything that you wish, for example:

$ git branch experimental_feature

Branching a branch or “I want more branches”.

You can create as many branches from inside any branch you want, creating a very dense tree if you like.

Just move inside (check-out that branch, see command 8 below) and issue the branch creation command.

Command 8 : Moving to a branch and listing all branches

Once you have created the branch move to it by issuing the command listed below. Always Make sure you do a commit before you issue this command or else changes will move across branches. Make this a habit! (OR have a look at git-stash command, discussed in part II of this tutorial.)

$ git checkout branch_name

Here the branch name is the branch where you want to move. Once checked-out, you can view staus, log, diff etc, using the commands presented earlier.

To go back to the master branch (the main trunk) issue the following command. (Again make sure you had issued the commit command)

$ git checkout master

Listing all branches

Issue the following command to see all available branches in the current repository.

$ git branch

Command 9 : Merging two branches

Move to (checkout) the branch with which you want the merge to happen and issue the following command.

$ git merge branch_name

This will merge the branch branch_name with the current branch.

For example if you want to merger the “experimental_feature” branch with the master branch, issue the following commands

$ git checkout master
$ git merge experimental_feature

Git will notify you with any conflicts it cannot resolve automatically (if any). You can then resolve the conflicts manually.

Deleting a branch

After the merge is done you can delete the experimental branch if you wish by issuing the command

$ git branch -d experimental_branch

The above command will only delete the branch if it is fully merged with the current branch’s HEAD. HEAD is the current position in your branch, the latest commit.

Command 10 : Deleting stuff from the repository.

Issue the following command if you do not want git to keep track of a file or folder and (this is the opposite of the git-add command). The file stays in the working directory, on the disk.

$ git rm --cached path/to/the/folder_or_file

The git-rm command removes the files from the repository for current HEAD only; previous revisions/commits will still have the file.

That’s it, you’re done!

Before I leave you a few more command/features that may interest you, but are not totally necessary as of now.

A graphical repository viewer

To invoke a graphical repository viewer, invoke the following command

$ gitk

Git – Graphical user interface

For those who prefer GUI, you can install a graphical front end to git.

On Fedora

$ yum install git-gui

On Ubuntu

$ apt-get install git-gui

Run the gui by issuing the following command

$ git-gui

Yup, totally done now!

That’s all folks. I hope this post will help you in getting started with one of the most powerful version control system available around.

When you are done playing with these commands, you may want to read the second installement of this turotial here: Git Tutorial Part II – Sharpen you Git-Fu with 10 more commands.

Git and Trac – A Love Story

Git and Trac, both got married very recently (at our setup ), and the newlywed couple are quite a charm to work with. It all started with the search for a version control tool which could be used now, with just four of us using it, and that would scale beautifully to hundreds and thousands of users. The version control system would be the groom. Meanwhile we were also in search for a perfect partner (the bride), an issue tracking system, that would gel with our choice of version control seamlessly.

To begin with, we all (at Hidden Reflex) were leaning towards a central repository setup ….. more