Revision as of 13:02, 9 September 2008 by Djarvie (talk | contribs) (First steps with Git: Fix log messages)
Jump to: navigation, search

This tutorial will show you the basics for Git. For more information, please consult for example the official tutorial introduction to Git or this excellent cheat sheet.

Setting up Git

First, you should tell Git your name and email address. These information will be shown in the log and in commits. Also, you should allow color in Git. There are other color-related features, but this tutorial is just about basics.

git config --global "Your Name"
git config --global [email protected]
git config --global color.ui true

In case you experience problems with colors you should test adding the following to you ~/.bashrc. The 'R' is the important part here.

#needed for git colours
export LESS="-RIM"

First steps with Git

We will start with a new Git repository and add one file to it.

[email protected]:~/git> git init
Initialized empty Git repository in .git/
[email protected]:~/git> echo "Test content" > testfile

Now we will check the status of the repository. Git will list one untracked file, that means the file has not yet been added to the repository.

[email protected]:~/git> git status
# On branch master
# Initial commit
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#       testfile
nothing added to commit but untracked files present (use "git add" to track)

In the next three commands the file 'testfile' will be added and commited. Then Git will check the status again.

[email protected]:~/git> git add testfile
[email protected]:~/git> git commit -m "This is the first commit"
Created initial commit 246d7aa: This is the first commit
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 testfile
[email protected]:~/git> git status
# On branch master
nothing to commit (working directory clean)

Ok, as you can see the file has been commited. Now let's see what we change the contents of the file:

[email protected]:~/git> echo "new content" > testfile
[email protected]:~/git> git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#       modified:   testfile
no changes added to commit (use "git add" and/or "git commit -a")
[email protected]:~/git> git commit -a -m "Second commit"
Created commit 14a9802: Second commit
 1 files changed, 1 insertions(+), 1 deletions(-)

You see that Git noticed the changes in the file. "git commit -a" commits all changes in the repository. Note: This command does not add newly created files.

Branches and merging are cheap in Git

git branch shows you the branches of the repository, the one with the '*' is the active one. So let us create a new branch called "bugfix-branch" and assume we want to fix a branch there. After this fix (in this case the new file) we will merge back all the hard work into the master branch.

[email protected]:~/git> git branch
* master
[email protected]:~/git> git branch bugfix-branch
[email protected]:~/git> git checkout bugfix-branch
Switched to branch "bugfix-branch"
[email protected]:~/git> git branch
* bugfix-branch
[email protected]:~/git> echo "a second file" > newfile
[email protected]:~/git> git commit -a
# On branch bugfix-branch
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#       newfile
nothing added to commit but untracked files present (use "git add" to track)
[email protected]:~/git> git add newfile
[email protected]:~/git> git commit
Created commit 3264357: This file is here for a demonstration of Gits branch- and merge feature
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 newfile

Ok, the bug is fixed now. Next step: Checkout the master branch and merge the two branches:

[email protected]:~/git> git checkout master
Switched to branch "master"
[email protected]:~/git> ls
[email protected]:~/git> git merge bugfix-branch
Updating 14a9802..3264357
Fast forward
 newfile |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 newfile
[email protected]:~/git> ls
newfile  testfile

If you would have edited "testfile" in the bugfix-branch, then git would automatically try to merge the contents of "testfile" in the bugfix-branch with the contents of "testfile" in the master branch. Sometimes this can cause a merge conflict. In that case you have to manually edit the "testfile" in the master branch, and afterwards you do a "git commit -a" to complete the merge. Git indicates the conflicting lines in the file itself.

Lets now have a look at the log of the testfile

[email protected]:~/git> git log testfile
commit 14a9802e249413003d1fa40002baa025aa54c75f
Author: Carsten Niehaus <[email protected]>
Date:   Fri Apr 18 18:07:18 2008 +0200

    Second commit

commit 246d7aad05139314e7ff62a5becb6c930f72fb8f
Author: Carsten Niehaus <[email protected]>
Date:   Fri Apr 18 18:06:33 2008 +0200

    This is the first commit

Interfacing KDE's SVN repository with git-svn

Note: Please make sure to use Git 1.5.4 or better when you are interfacing with SVN. git-svn in older version has many issues you might run into otherwise.

Note: git-svn is not able to track most of the svn:properties yet. So, e.g. svn:externals are not fetched.

Here I'm going to explain to you how to fetch KDE-EDU-trunk and import it into Git. I will then demonstrate how to make use of Git's features and sync with SVN again.

git svn init
git svn fetch -r798745

For those who don't have a password set up for https access, or who would rather use the more traditional SSH+SVN approach an alternate initialization line for the git repository (replace USERNAME with your username).

git svn init svn+ssh://[email protected]/home/kde/trunk/KDE/kdeedu

The revision has to be an existing revision of the module (to be found here).

To later update (sync with SVN) do:

git svn rebase

Now you can do everything you want, for example creating as many local branches as you like and merge back and forth. Whenever you want you can use this command to push your changes back into KDE's SVN repository:

git svn dcommit

Be warned, Git will create one SVN commit for each commit in your Git repository. To create just one commit for the whole merge of a branch into the master branch use the "--squash" feature like this:

git merge --squash mybranch

Handling local changes

git-svn cannot sync with SVN when you have local, uncommited changes. For that you are using git stash. That command move the local changes on a stack so that you can sync. After the sync you re-apply them to you Git tree and clear the stack. Very handy feature in many situations! Just do this:

git stash
git svn rebase
git stash apply
git stash clear

If you have local changes which you would like to revert use the following command. It will revert all local, uncommited changes.

git checkout -f

Final words

This tutorial is really just a start for Git. Another great Git-SVN tutorial is this one.

Content is available under Creative Commons License SA 4.0 unless otherwise noted.