Difference between revisions of "Development/Tutorials/Git/Basics"

Jump to: navigation, search
(Use code, not pre)
 
(15 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
{{warning|This page is yet to be reviewed for changes required by the migration to Git.  Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}
 +
 
This tutorial will show you the basics for [http://git-scm.com/ Git].
 
This tutorial will show you the basics for [http://git-scm.com/ Git].
  
 
== Setting up Git ==
 
== 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.
+
For Git to work properly, it needs to store some personal information for use in email merge requests and in the commit logging.
  
<pre>
+
<syntaxhighlight lang="text">
 
git config --global user.name "Your Name"
 
git config --global user.name "Your Name"
 
git config --global user.email you@example.com
 
git config --global user.email you@example.com
 +
</syntaxhighlight>
 +
 +
Additionally, to allow colorized output in Git:
 +
 +
<syntaxhighlight lang="text">
 
git config --global color.ui true
 
git config --global color.ui true
</pre>
+
</syntaxhighlight>
 +
 
 +
There are other additional color-related features which are discussed in the fine documentation that comes with Git.
  
In case you experience problems with colors you should test adding the following to your ~/.bashrc. The 'R' is the important part here.
+
If you experience problems with colorized output, try adding the following to your <tt>~/.bashrc</tt>
  
<pre>
+
<syntaxhighlight lang="text">
 
# R needed for git colours
 
# R needed for git colours
 
export LESS="-RIM"
 
export LESS="-RIM"
</pre>
+
</syntaxhighlight>
 
+
  
 
== First steps with Git ==
 
== First steps with Git ==
  
There are two ways to get started with Git for KDE. If you're only wanting to get code to try it out, you can use the following commands:
+
Getting started with Git for KDE is fairly easy. First, run the following:
  
<code>
+
<syntaxhighlight lang="text">
 
git clone <REPOSITORY URL>
 
git clone <REPOSITORY URL>
</code>
+
</syntaxhighlight>
  
This creates a local copy of the upstream repository. Now change into that directory and code away. When you want to update:
+
The <tt><REPOSITORY URL></tt> for the KDE-Qt repository is discussed on the  [http://techbase.kde.org/Getting_Started/Build/KDE4/Prerequisites#Qt Qt Prerequisites] wiki page.
  
<code>
+
This creates a local copy of the upstream repository, in your local <tt>master</tt> branch. Always keep the <tt>master</tt> branch for tracking the upstream repository, and create other branches to do your work in. That way, it will be straightforward to push selected changes upstream, rather than having to push all your changes every time.
git pull
+
</code>
+
  
Later, if you want to create a new Git repository and add files to it, try the preceeding commands:
+
Create a work branch (in this example, called <tt>mywork</tt>), and change to that branch:
  
<code>
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git init
+
git branch mywork
Initialized empty Git repository in .git/
+
git checkout mywork
carsten@moinmoin:~/git> echo "Test content" > testfile
+
</syntaxhighlight>
</code>
+
  
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.
+
Now change into the git directory and code away. To fetch upstream changes into your local repository, switch to the master branch and run:
  
<pre>
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git status
+
git checkout master
 +
git pull --rebase
 +
</syntaxhighlight>
 +
 
 +
To update another branch from master, without losing changes already committed in the branch:
 +
 
 +
<syntaxhighlight lang="text">
 +
git checkout mywork
 +
git merge master
 +
</syntaxhighlight>
 +
 
 +
To check the status of the repository. use the <tt>status</tt> sub-command to view the state of the local copy:
 +
 
 +
<syntaxhighlight lang="text">
 +
$ git status
 
# On branch master
 
# On branch master
 
#
 
#
Line 54: Line 73:
 
#      testfile
 
#      testfile
 
nothing added to commit but untracked files present (use "git add" to track)
 
nothing added to commit but untracked files present (use "git add" to track)
</code>
+
</syntaxhighlight>
  
In the next three commands the file 'testfile' will be added and commited. Then  Git will check the status again.
+
If 'testfile' should be added to the local copy, run the <tt>add</tt> sub command:
  
<code>
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git add testfile
+
$ git add testfile
carsten@moinmoin:~/git> git commit -m "This is the first commit"
+
</syntaxhighlight>
 +
 
 +
Once 'testfile' has all the changes desired, <tt>commit</tt> it to the local copy:
 +
 
 +
<syntaxhighlight lang="text">
 +
$ git commit -m "This is the first commit"
 
Created initial commit 246d7aa: This is the first commit
 
Created initial commit 246d7aa: This is the first commit
 
  1 files changed, 1 insertions(+), 0 deletions(-)
 
  1 files changed, 1 insertions(+), 0 deletions(-)
 
  create mode 100644 testfile
 
  create mode 100644 testfile
carsten@moinmoin:~/git> git status
+
</syntaxhighlight>
# On branch master
+
nothing to commit (working directory clean)
+
</code>
+
  
Ok, as you can see the file has been commited. Now let's see what we change the contents of the file:
+
Much like <tt>svn status</tt>, if you change a file once it has been committed, running <tt>git status</tt> will show that the file was modifed since last commit:
  
<code>
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> echo "new content" > testfile
+
$ echo "new content" > testfile
carsten@moinmoin:~/git> git status
+
$ git status
 
# On branch master
 
# On branch master
 
# Changed but not updated:
 
# Changed but not updated:
Line 81: Line 102:
 
#
 
#
 
no changes added to commit (use "git add" and/or "git commit -a")
 
no changes added to commit (use "git add" and/or "git commit -a")
carsten@moinmoin:~/git> git commit -a -m "Second commit"
+
</syntaxhighlight>
Created commit 14a9802: Second commit
+
1 files changed, 1 insertions(+), 1 deletions(-)
+
</code>
+
  
You see that Git noticed the changes in the file. <i>"git commit -a"</i> commits all changes in the repository. Note: This command does not add newly created files.
+
As the output states, the changes will not be added to the commit before you use <tt>git add</tt> to add the files to your staging area. The staging area is a temporary location for the changes to be commited, and it basically allows you to select what files you want to include in a commit. If you want to include all changed files to your next commit, the shortcut "-a" for commit can be used to achieve this.
 +
 
 +
After the files have been added to the staging area, <tt>git diff</tt> will not show changes to them. To check your changes before doing the commit, you can pass <tt>--cached</tt> as an option to diff to see them.
 +
 
 +
To push your changes in the current branch to the upstream repository:
 +
 
 +
<syntaxhighlight lang="text">git push</syntaxhighlight>
  
 
== Branches and merging are cheap in Git ==
 
== Branches and merging are cheap in Git ==
  
<i>git branch</i> shows you the branches of the repository, the one with the '*' is the active one. So let us create a new branch called <i>"bugfix-branch"</i> 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.
+
When creating changes to the code from the upstream repository that will later get merged back upstream, branches are highly recommended.
  
<code>
+
To view the current set of branches available, run <tt>git branch</tt>. The branch with a proceeding '*' is the active one. To create a new branch called <tt>"bugfix-branch"</tt> for example, run:
carsten@moinmoin:~/git> git branch
+
 
* master
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git branch bugfix-branch
+
$ git branch bugfix-branch
carsten@moinmoin:~/git> git checkout bugfix-branch
+
$ git checkout bugfix-branch
 
Switched to branch "bugfix-branch"
 
Switched to branch "bugfix-branch"
carsten@moinmoin:~/git> git branch
+
</syntaxhighlight>
* bugfix-branch
+
 
  master
+
There is also an alias for that
carsten@moinmoin:~/git> echo "a second file" > newfile
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git commit -a
+
$ git checkout -b bugfix-branch
# On branch bugfix-branch
+
Switched to a new branch "bugfix-branch"
# Untracked files:
+
</syntaxhighlight>
#  (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)
+
carsten@moinmoin:~/git> git add newfile
+
carsten@moinmoin:~/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
+
</code>
+
  
Ok, the bug is fixed now. Next step: Checkout the master branch and merge the two branches:
+
Make the necessary changes to the branch and then get ready to merge them back to the master branch
  
<code>
+
<syntaxhighlight lang="text">
carsten@moinmoin:~/git> git checkout master
+
$ git checkout master
 
Switched to branch "master"
 
Switched to branch "master"
carsten@moinmoin:~/git> ls
+
$ ls
 
testfile
 
testfile
carsten@moinmoin:~/git> git merge bugfix-branch
+
$ git merge bugfix-branch
 
Updating 14a9802..3264357
 
Updating 14a9802..3264357
 
Fast forward
 
Fast forward
Line 129: Line 143:
 
  1 files changed, 1 insertions(+), 0 deletions(-)
 
  1 files changed, 1 insertions(+), 0 deletions(-)
 
  create mode 100644 newfile
 
  create mode 100644 newfile
carsten@moinmoin:~/git> ls
+
$ ls
 
newfile  testfile
 
newfile  testfile
</code>
+
</syntaxhighlight>
  
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.
+
If there had been changes made to the branch, git would have automatically tried to merge the changes in the bugfix-branch with the master branch.  
  
== Lets now have a look at the log of the testfile ==
+
Rarely, this can cause a merge conflict. In those cases, manually edit the files that conflict in the master branch, and then do a <tt>git commit -a</tt> to complete the merge. Git indicates the conflicting lines within the file that cannot be auto-merged.
  
<code>
+
== Viewing the Change log ==
carsten@moinmoin:~/git> git log testfile
+
 
 +
To view the change log for a given file in the local copy, run <tt>git log <FILENAME></tt>.
 +
 
 +
<syntaxhighlight lang="text">
 +
$ git log testfile
 
commit 14a9802e249413003d1fa40002baa025aa54c75f
 
commit 14a9802e249413003d1fa40002baa025aa54c75f
 
Author: Carsten Niehaus <carsten@moinmoin.site>
 
Author: Carsten Niehaus <carsten@moinmoin.site>
Line 150: Line 168:
  
 
     This is the first commit
 
     This is the first commit
</code>
+
</syntaxhighlight>
 
+
== Handling local changes ==
+
 
+
git-svn cannot sync with SVN when you have local, uncommited changes. For that you are using <i>git stash</i>. 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:
+
 
+
<code>
+
git stash
+
git svn rebase
+
git stash apply
+
git stash clear
+
</code>
+
 
+
If you have local changes which you would like to revert use the following command. It will revert all local, uncommited changes.
+
  
<code>
+
To ease the workflow you can use <tt>git log -p</tt> to see the diffs per commit basis, instead of querying the commit hash with <tt>git log</tt> and then using <tt>git diff</tt> against that.
git checkout -f
+
</code>
+

Latest revision as of 20:45, 24 March 2012

noframe
 
Warning
This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the KDE Git hub page for more details.


This tutorial will show you the basics for Git.

Contents

[edit] Setting up Git

For Git to work properly, it needs to store some personal information for use in email merge requests and in the commit logging.

git config --global user.name "Your Name"
git config --global user.email you@example.com

Additionally, to allow colorized output in Git:

git config --global color.ui true

There are other additional color-related features which are discussed in the fine documentation that comes with Git.

If you experience problems with colorized output, try adding the following to your ~/.bashrc

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

[edit] First steps with Git

Getting started with Git for KDE is fairly easy. First, run the following:

git clone <REPOSITORY URL>

The <REPOSITORY URL> for the KDE-Qt repository is discussed on the Qt Prerequisites wiki page.

This creates a local copy of the upstream repository, in your local master branch. Always keep the master branch for tracking the upstream repository, and create other branches to do your work in. That way, it will be straightforward to push selected changes upstream, rather than having to push all your changes every time.

Create a work branch (in this example, called mywork), and change to that branch:

git branch mywork
git checkout mywork

Now change into the git directory and code away. To fetch upstream changes into your local repository, switch to the master branch and run:

git checkout master
git pull --rebase

To update another branch from master, without losing changes already committed in the branch:

git checkout mywork
git merge master

To check the status of the repository. use the status sub-command to view the state of the local copy:

$ 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)

If 'testfile' should be added to the local copy, run the add sub command:

$ git add testfile

Once 'testfile' has all the changes desired, commit it to the local copy:

$ 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

Much like svn status, if you change a file once it has been committed, running git status will show that the file was modifed since last commit:

$ echo "new content" > testfile
$ 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")

As the output states, the changes will not be added to the commit before you use git add to add the files to your staging area. The staging area is a temporary location for the changes to be commited, and it basically allows you to select what files you want to include in a commit. If you want to include all changed files to your next commit, the shortcut "-a" for commit can be used to achieve this.

After the files have been added to the staging area, git diff will not show changes to them. To check your changes before doing the commit, you can pass --cached as an option to diff to see them.

To push your changes in the current branch to the upstream repository:

git push

[edit] Branches and merging are cheap in Git

When creating changes to the code from the upstream repository that will later get merged back upstream, branches are highly recommended.

To view the current set of branches available, run git branch. The branch with a proceeding '*' is the active one. To create a new branch called "bugfix-branch" for example, run:

$ git branch bugfix-branch
$ git checkout bugfix-branch
Switched to branch "bugfix-branch"

There is also an alias for that

$ git checkout -b bugfix-branch
Switched to a new branch "bugfix-branch"

Make the necessary changes to the branch and then get ready to merge them back to the master branch

$ git checkout master
Switched to branch "master"
$ ls
testfile
$ git merge bugfix-branch
Updating 14a9802..3264357
Fast forward
 newfile |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 newfile
$ ls
newfile  testfile

If there had been changes made to the branch, git would have automatically tried to merge the changes in the bugfix-branch with the master branch.

Rarely, this can cause a merge conflict. In those cases, manually edit the files that conflict in the master branch, and then do a git commit -a to complete the merge. Git indicates the conflicting lines within the file that cannot be auto-merged.

[edit] Viewing the Change log

To view the change log for a given file in the local copy, run git log <FILENAME>.

$ git log testfile
commit 14a9802e249413003d1fa40002baa025aa54c75f
Author: Carsten Niehaus <carsten@moinmoin.site>
Date:   Fri Apr 18 18:07:18 2008 +0200
 
    Second commit
 
commit 246d7aad05139314e7ff62a5becb6c930f72fb8f
Author: Carsten Niehaus <carsten@moinmoin.site>
Date:   Fri Apr 18 18:06:33 2008 +0200
 
    This is the first commit

To ease the workflow you can use git log -p to see the diffs per commit basis, instead of querying the commit hash with git log and then using git diff against that.


This page was last modified on 24 March 2012, at 20:45. This page has been accessed 5,469 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal