Xfce uses GIT as distributed version control system (DCVS) for all the code contributed by developers. On this page we will explain the basics and initial setup the get started, but if you want to know it all look at the following websites:

• Official books and reference manual
• Use man git <command> in your terminal emulator
• Your favorite search engine

Tips and Tricks
Some additional functionality that is nice to know.

User repositories
How to create a user repositories.

GitHub mirror
What we do with the GitHub mirror of the Xfce repositories.

Before you even think about committing changes, you must set your name and email address to something valid in your local Git config:

git config --global user.name "J. Random Hacker"
git config --global user.email "jrandom@example.com"

Make sure the email address is a valid address, there is a hook on the server that checks the address of every new commit.

Because the intention is not to explain Git, only a short introduction on how it works to get you started. You can find the clone URL in the summary page of each repository in the Git browser.

In the example below we do some tasks in the xfwm4 repository.

# Make a local clone of the upstream repository
git clone git://git.xfce.org/xfce/xfwm4
 
# To keep the local copy updated with upstream you can run this from time to time
# Possibly append --rebase to fetch upstream changes and apply you modifications on
# top of those, instead of trying to merge them
git pull
 
# If you made some small modifications in the code you can view them in a unified patch
git diff
git status
 
# Redirect to a patch for in bugzilla (without credits and message)
git diff > ~/fix-for-bug-1234.patch 

In case the changes are more invasive, it is best to work in a separate branch. You can there commit all the individual modifications and when finished create a patch bundle.

# Create a branch to work in
git checkout -b my-fix-for-1234
 
# Make changes and commit them
git commit
 
# In case upstream changed a lot...
git checkout master          # switch back to the master branch
git pull                     # pull the latest upstream changes
git checkout my-fix-for-1234 # switch back to your branch
git rebase master            # rebase your branch on top of the updated master
 
# Time to create the patches (that are in your branch and not in master)
git format-patch -o ~/output/directory/ --signoff master

In the output directory you should find various 0001-message.patch files. Those are suitable to attach in a bug in the bug tracker.

What ever you do, keep commits clean:

• Make incremental, atomic changes (one aspect at a time).
• Keep code working after every commit.
• Comment the code you write.
• Write commit messages using the standard Git message format.
• Don't fear the rebase (against the Xfce master branch): you should fix the merge problems, not the developer.

There are a number of rules we enforce in the upstream repositories. If you are experimenting with code (and thus working with more branches and rebasing) it is therefore advised to do this in a user repository and wait with the merge upstream when everything is ready.

To list all your permissions and repositories you can access to, run the following command:

# W means you can write, R is read-only
ssh git@git.xfce.org info

For non-user repositories the following rules apply as well:

• You can only push fast-forward commits (upstream can not loose refs)
• Email addresses of each commit are validated
• You can only create and delete branches starting with your $sshname
• Only annotated tags are allowed, tags cannot be deleted

Set the description file contents at the remote repository. The description is used in the CGit web interface.

ssh git@git.xfce.org desc users/$user/$name "Your single-line repository description for cgit"

Every user with write access to the repository can change the description. The CGit interface is updated with a cronjob, so it might take up to 15 minutes before the new description is visible.

TODO SSKM