== Ubuntu X-SWAT uses git now ==
We are now using git for the packages with biggest set of changes.  This page is a simplified version of [[http://wiki.debian.org/XStrikeForce/git-usage|the Debian git-usage]] page specifically for our needs.

There is also a web interface to review changes: [[http://git.debian.org/]].

Direct links to current Ubuntu branches:
 * [[http://git.debian.org/?p=pkg-xorg/lib/mesa.git;a=shortlog;h=ubuntu|mesa]]
 * [[http://git.debian.org/?p=pkg-xorg/debian/xorg.git;a=shortlog;h=ubuntu|xorg]]
 * [[http://git.debian.org/?p=pkg-xorg/xserver/xorg-server.git;a=shortlog;h=ubuntu|xorg-server]]
 * [[http://git.debian.org/?p=pkg-xorg/lib/libx11.git;a=shortlog;h=refs/heads/ubuntu|libx11]]
 * [[http://git.debian.org/?p=pkg-xorg/lib/libdrm.git;a=shortlog;h=ubuntu|libdrm]]
 * [[http://git.debian.org/?p=pkg-xorg/lib/xft.git;a=shortlog;h=refs/heads/ubuntu|xft]]
 * [[http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-input-evdev.git;a=shortlog;h=ubuntu|xserver-xorg-input-evdev]]

== Git archive policy ==

Currently we only branch a few packages, since those have the most changes and have traditionally been painful to merge. The rest are better to just remain sync'able or merged when there are small changes. Changes that benefit Debian are being pushed back so that the delta is kept as small as possible.

== Basic tutorial ==

First you need to pull the repository on your disk, and change the working branch. This is also the procedure to create the initial ubuntu branch. For instance to pull xorg you would do:

{{{
git clone ssh://user-guest@git.debian.org/git/pkg-xorg/debian/xorg.git
git checkout -b ubuntu origin/ubuntu
 HEAD is now at cdbd698... Prepare changelog for upload.
 Switched to branch "ubuntu"
}}}

But if you've already done that in the past, you need to update your local branch to match remote (TODO: what if there are local changes?)

{{{
# make sure you are on the correct local branch
git checkout ubuntu
# pull from git.debian.org
git pull
}}}

Check the success by running these
{{{
git status
 # On branch ubuntu
 nothing to commit (working directory clean)
git log
}}}
The first thing usually is to merge with a new Debian release. The simplest way to do it is to use git-merge(1) (note that Debian release tags use a hyphen, where upstream tags use underscores)
{{{
git merge <tag>
}}}
It most likely complains that there are conflicts, so then make sure you have a merge tool of your choice installed (meld is one alternative) and then run git-mergetool
{{{
git mergetool
 Merging the files: debian/changelog debian/control

 Normal merge conflict for 'debian/changelog':
  {local}: modified
  {remote}: modified
 Hit return to start merge resolution tool (meld): 
}}}
Merge leaves behind some temporary files if there are conflicts, so clean them.
{{{
git clean
 Removing debian/changelog.orig
 Removing debian/control.orig
}}}
Now you can do other changes if necessary. Remember to git-add new files.
{{{
<edit>
git add path/to/a-new-file
dch
git diff
}}}
and commit them.
{{{
git commit -a
}}}
When everything is set, push the changes to the repository.
{{{
git push origin ubuntu
}}}
Now it's safe to do a release. Don't forget to add -i/I as necessary, and put the tarball in the parent directory before running debuild.
{{{
debuild -I".git" -S -sa -v$previousUbuntuVersion ### for xorg
debuild -i".git" -S -sa -v$previousUbuntuVersion ### for rest with an orig.tar.gz
}}}
After reviewing the resulting package (debdiff et al) it is ready for upload!

== Recovering from mistakes ==

There are (at least) two ways to revert a change, either reverting and older commit with
{{{
git revert <hash>
}}}
or by resetting the HEAD if you want to just revert the latest (set of) change(s)
{{{
git reset --hard <hash of the new HEAD>
}}}

or alternately use this to go back revisions, replacing 1 with how many you wish to go back.
{{{
git reset --hard HEAD~1
}}}

Reverting leaves a message on the log, so it's not a "clean" way to undo changes, but necessary when the changes are already committed to the repository, or when there are changes made after that commit.

Sometimes you need to clean up the mess you've done and start from a clean table. In that case you'd better just first clean all local changes
{{{
git clean -xdf
}}}
And then reset to the head of the remote ubuntu branch
{{{
git reset --hard origin/ubuntu
}}}

== Merging a new upstream release ==

When merging new upstream releases, it's common to have conflicts due to differences between the branches etc. Sometimes git can't handle the merge gracefully, so you need to do:

{{{
# optionally cleanup your local repo
git clean -df

# checkout the upstream branch you want
git checkout -b new-branch upstream/master

# tell git that we've merged the changes of the old branch and ignore any changes
# that are there
git merge -s ours mesa_7_2

# now pull in the packaging branch
git merge debian-experimental

# ..and handle the conflicts (if any)
sudo apt-get install meld
git mergetool

# Check your work
git status

# Then commit the merge
git commit -a
}}}

== Starting a new git tree ==

If you have a new project to put into git, first initialize a fresh new repository:

{{{
mkdir xorg-my-tree
cd xorg-my-tree
git init
}}}

Add files as usual:

{{{
echo "$DEBFULLNAME <$DEBEMAIL>" > AUTHORS
git add AUTHORS
git commit -m "Initial creation of tree"
}}}

Tag the start of your project if you wish:

{{{
echo "[user]
        signingkey = $DEBEMAIL
" >> .git/config
git tag -s INITIAL
}}}

Then to publish it, first initialize the external git repo on alioth:
{{{
ssh user-guest@alioth.debian.org
mkdir -p ~/public_html/git/xorg-my-tree.git
cd ~/public_html/git/
GIT_DIR=xorg-my-tree.git git-init
chmod +x xorg-my-tree.git/hooks/post-update
}}}

And then from your local machine, push your initial release up:
{{{
git push user-guest@alioth.debian.org:public_html/git/xorg-my-tree.git master
git repack
}}}

== Creating a new branch for an older Ubuntu release ==

Say you have a patch to mesa for a previous Ubuntu release.

First, check out the current git tree for Ubuntu development as above.  Then check out the last commit for the Ubuntu release you wish to patch.

{{{
git checkout <LAST-REF> -b ubuntu-oneiric
}}}

Now, add your patch, changelog entry, and so on, and push the branch back to debian git:

{{{
git commit -a -m "Cherrypick of upstream patch"
git push ssh://user-guest@git.debian.org/git/pkg-xorg/lib/mesa.git ubuntu-oneiric
}}}

== Useful commands ==

Check the tree for spurious files (could be left after a merge from upstream etc)
{{{
git clean -dnx
}}}

Cherrypick a fix from Debian's upstream snapshot and add it as a patch:
{{{
git pull
git checkout origin/upstream-experimental -b upstream-experimental
git log
# Locate the desired commit <REF>
git checkout ubuntu
git cherry-pick REF
git show REF > ./debian/patches/100_foo_bar.patch
git reset --hard HEAD^
git add debian/patches/100_foo_bar.patch
dch -i -m "Cherrypick REF from upstream as 100_foo_bar.patch"
git commit -a -m "Cherrypick REF from upstream as 100_foo_bar.patch"
}}}