Simple Workflow

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the Feature Branch Workflow.

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

If you have a slow or intermittent internet connection then you may prefer to download a snapshot tarball to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

Local Feature Development

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

Making Local Change Commits

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:

Locally modified files can have different states that determine whether they get committed or not.

Committing code is only local, it does not merge your changes into the central repository which requires an extra step.

Files in a git repository can be in various states:

Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.

Tracked: Files that git tracks changes to.

Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.

Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit

Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can also be modified before you finally do merge the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

Seeing What You Changed

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

Pushing Your Changes To The Central Repository

When you are ready to merge all your local commits into the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to stash the changes.

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

Local Bug Fixing

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the Feature Branch Workflow.

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the Feature Branch Workflow.

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository: