|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.
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 email@example.com </code> Additionally, to allow colorized output in Git: <syntaxhighlight lang="text"> git config --global color.ui true </code> 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 <tt>~/.bashrc</tt> <syntaxhighlight lang="text"> # R needed for git colours export LESS="-RIM" </code> == First steps with Git == Getting started with Git for KDE is fairly easy. First, run the following: <syntaxhighlight lang="text"> git clone <REPOSITORY URL> </code> 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. 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. Create a work branch (in this example, called <tt>mywork</tt>), and change to that branch: <syntaxhighlight lang="text"> git branch mywork git checkout mywork </code> Now change into the git directory and code away. To fetch upstream changes into your local repository, switch to the master branch and run: <syntaxhighlight lang="text"> git checkout master git pull --rebase </code> To update another branch from master, without losing changes already committed in the branch: <syntaxhighlight lang="text"> git checkout mywork git merge master </code> 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 # # 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) </code> If 'testfile' should be added to the local copy, run the <tt>add</tt> sub command: <syntaxhighlight lang="text"> $ git add testfile </code> 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 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 testfile </code> 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: <syntaxhighlight lang="text"> $ 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") </code> 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</code> == 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 <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: <syntaxhighlight lang="text"> $ git branch bugfix-branch $ git checkout bugfix-branch Switched to branch "bugfix-branch" </code> There is also an alias for that <syntaxhighlight lang="text"> $ git checkout -b bugfix-branch Switched to a new branch "bugfix-branch" </code> Make the necessary changes to the branch and then get ready to merge them back to the master branch <syntaxhighlight lang="text"> $ 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 </code> 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 <tt>git commit -a</tt> to complete the merge. Git indicates the conflicting lines within the file that cannot be auto-merged. == Viewing the Change log == 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 Author: Carsten Niehaus <firstname.lastname@example.org> Date: Fri Apr 18 18:07:18 2008 +0200 Second commit commit 246d7aad05139314e7ff62a5becb6c930f72fb8f Author: Carsten Niehaus <email@example.com> Date: Fri Apr 18 18:06:33 2008 +0200 This is the first commit </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.