--- /dev/null
+/files
+/*.log
+/topgit
--- /dev/null
+Using TopGit to generate quilt series for Debian packaging
+----------------------------------------------------------
+
+You have been referred to this document probably because a source package you
+are working on uses TopGit to generate a quilt series to encapsulate
+differences between upstream and the source code used for the Debian package.
+
+Please make sure that you have a recent version of TopGit (>= 0.5) installed
+before trying any of this.
+
+Where appropriate, the examples use the topgit package itself to illustrate
+the use. I trust you to be able to make the appropriate amendments for your
+situation.
+
+1. Cloning the repository
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Cloning a TopGit repository requires an additional step to normal Git cloning:
+
+1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
+2. cd topgit
+3. tg remote --populate origin
+
+You can also use the debcheckout tool from the devscripts package:
+
+ debcheckout topgit
+
+which will do all the above for you automatically.
+
+Branches in use
+'''''''''''''''
+The following branches are in use in the topgit package. You are free to
+deviate from this set for the package you are working on, but then please
+document it accordingly in your README.source.
+
+- upstream: tracks the upstream Git repository
+- fixes/*: patches fixing problems with upstream
+- features/*: patches providing new features, targetted upstream
+- master: the main Debianisation branch
+- debian/*: Debian-specific patches
+
+upstream and master are regular Git branches, while the others are TopGit
+branches. The reason why master is not a TopGit branch itself is so that it's
+possible to export all TopGit-managed branches into the quilt series, without
+having to make an exception for master.
+
+2. Developing a new feature
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to develop a new feature (or bug fix), first consider whether the
+patch is intended to go upstream or is a Debian-specific change. Choose the
+namespace accordingly and base it off upstream or master respectively. If the
+patch depends on another patch, obviously base it off the respective TopGit
+branch.
+
+The following are the steps required to add a feature branch/patch:
+
+1. tg create features/new-feature upstream
+ - or -
+ tg create debian/new-debian-stuff master
+
+2. edit .topmsg and make the subject line be a short description, optionally
+ add a longer description to the body
+
+3. git add .topmsg && git commit
+
+3. Obtaining the upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The upstream tarball for the topgit package $VERSION can be obtained using
+pristine-tar:
+
+ pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
+
+4. Building the package
+~~~~~~~~~~~~~~~~~~~~~~~
+Building the package is trivial, thanks to the inclusion of the tg2quilt.mk
+snippet at the top of debian/rules.
+
+Unless you set the TG_BRANCHES variable before the include statement (or when
+you invoke debian/rules (or make), tg2quilt will simply export all TopGit
+branches into the quilt series. You can set the variable TG_BRANCHES to
+a space- or comma-separated list (but not comma and space) of feature branches
+to export, e.g.:
+
+ TG_BRANCHES := branch1,branch2
+ TG_BRANCHES := 'branch3 branch4 branch 5'
+
+Building the package requires no additional steps over other Debian packages.
+
+Since it is currently not possible to access TopGit branches for previous
+versions of a package (#500656), it is a good idea to maintain a build branch,
+into which you merge the master (Debianisation) branch whenever making a new
+release, and where you simply track the contents of the debian/patches
+directory. This can conveniently become the branch from which you build:
+
+1. git checkout build
+2. git merge master
+3. ./debian/rules tg-cleanexport
+4. git add debian/patches
+5. git commit -m'preparing $VERSION'
+6. build, test, upload, tag ('debian/topgit-$VERSION')
+
+TODO: add a debian/NEWS entry to get people to switch to using this approach.
+
+5. Importing a new upstream version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To import a new upstream, update the remote, merge the tag you want to merge
+into the master branch, ideally together with an update to debian/changelog,
+then update all TopGit branches:
+
+1. git remote update
+2. git checkout master
+3. git merge <new-upstream-tag>
+
+Now proceed as in the next step.
+
+6. Making changes to the master branch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you make changes to the master branch (the "debianisation" branch), follow
+this procedure:
+
+1. tg summary
+2. for every branch that is prefixed with 'D' in the output:
+ git checkout $BRANCH && tg update
+
+7. Building an upstream tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you are using pristine-tar, the follopwing can be used to commit an
+upstream tarball to the repository. It makes sense to rename it according to
+the Debian-standard package_version.orig.tar.gz convention first.
+
+1. pristine-tar commit ../topgit_$VERSION.orig.tar.gz <upstream-tag>
+
+If upstream does not provide tarballs, you can create the orig.tar.gz file and
+commit is as follows:
+
+1. git checkout topgit-$VERSION
+2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
+ | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
+3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
+ HEAD
+4. git checkout master
+
+
+
+All comments and suggestions are welcome, especially those pertaining to
+auto-generating debian/changelog from commit logs.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:16:03 +0100
--- /dev/null
+topgit (0.5-1) unstable; urgency=low
+
+ The Debian topgit package now provides a Makefile snippet for inclusion from
+ debian/rules, to facilitate the creation of a quilt series from TopGit
+ branches during the package build (and cleanup) step. Please refer to
+ /usr/share/doc/topgit/HOWTO-tg2quilt.gz and /usr/share/topgit/tg2quilt.mk
+ for more information. You can see it in action in the topgit package itself.
+
+ To stop the proliferation of TopGit boilerplate, which could make later
+ maintenance and changes more difficult, you are encouraged to make use of
+ the snippet.
+
+ If you have ideas for other features, I'd be happy to incorporate them.
+ Patches most welcome.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:23:52 +0100
--- /dev/null
+topgit for Debian
+-----------------
+
+TopGit is itself managed with TopGit. Per Debian policy, have a look into
+README.source to see how this is done.
+
+ -- martin f. krafft <madduck@debian.org> Mon, 11 Aug 2008 17:32:48 -0300
--- /dev/null
+Building topgit for Debian
+--------------------------
+
+The topgit source package uses quilt to apply and remove its patches. Please
+refer to /usr/share/doc/quilt/README.source for information about how to use
+quilt for source packages.
+
+The quilt series is generated from the Git repository, using TopGit itself.
+This process is documented in /usr/share/doc/topgit/HOWTO-tg2quilt.gz .
+
+The topgit packages uses the branch layout described in the aforementioned
+document.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:17:09 +0100
--- /dev/null
+topgit (0.5-2) unstable; urgency=low
+
+ * Provide new tg2quilt target tg-cleanexport, which recreates debian/patches
+ in one step.
+ * Actually install the bash completion script; thanks to Uwe Kleine-König
+ for noticing and providing a patch (closes: #499072).
+ * Add a note to tg2quilt.mk's header explaining the need to soft-include
+ tg2quilt.mk, to avoid the topgit build-dependency.
+ * Suggest the git-email package (closes: #508079).
+ * Suggest the make and quilt packages.
+ * Fix GPL version in copyright file (closes: #514157).
+ * Deprecate tg2quilt.mk's $PATCHES_DIR variable and put a warning in place
+ to point people to $QUILT_PATCH_DIR instead.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 17:58:45 +0100
+
+topgit (0.5-1) unstable; urgency=low
+
+ * New upstream release (closes: #500273, #505266).
+ * Upstream added bash completion (closes: #499072).
+ * Provide the tg2quilt Makefile snippet for inclusion from debian/rules to
+ facilitate generation of the quilt series from TopGit branches. See
+ /usr/share/doc/topgit/HOWTO-tg2quilt.gz for details; thanks to Stefano
+ Zacchiroli for the idea that led to this (closes: #501991, #506072).
+ * Update the README.source workflow to refer to HOWTO-tg2quilt.
+ * Add a NEWS file to make sure people get notified of this change.
+
+ -- martin f. krafft <madduck@debian.org> Fri, 26 Sep 2008 19:55:58 +0200
+
+topgit (0.3-1) unstable; urgency=low
+
+ * New upstream release (closes: #498559).
+ * Retire fixes/destdir branch as upstream does it better; amend debian/rules
+ to set $prefix instead of $PREFIX.
+ * Updated README.source to reflect TopGit remote handling and slight changes
+ to the process.
+
+ -- martin f. krafft <madduck@debian.org> Wed, 10 Sep 2008 09:31:03 +0100
+
+topgit (0.2-1) unstable; urgency=low
+
+ * Initial release (closes: #494710).
+
+ -- martin f. krafft <madduck@debian.org> Mon, 11 Aug 2008 17:32:48 -0300
+
--- /dev/null
+Source: topgit
+Section: devel
+Priority: optional
+Maintainer: Debian TopGit maintainers <pkg-topgit@teams.debian.net>
+Uploaders: martin f. krafft <madduck@debian.org>, Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
+Build-Depends: debhelper (>= 6), quilt
+Standards-Version: 3.8.0
+Homepage: http://repo.or.cz/w/topgit.git
+Vcs-Git: git://git.debian.org/git/collab-maint/topgit.git
+Vcs-Browser: http://git.debian.org/?p=collab-maint/topgit.git
+
+Package: topgit
+Architecture: all
+Depends: git-core
+Suggests: git-email, make, quilt
+Description: a Git patch queue manager
+ TopGit manages a patch queue using Git topic branches, one patch per
+ branch. It allows for patch dependencies and can thus manage
+ non-linear patch series.
+ .
+ TopGit is a minimal layer on top of Git, which does not limit use of
+ Git's functionality (such as the index). It rigorously keeps history
+ until a patch is accepted upstream. It is also fully usable across
+ distributed repositories.
--- /dev/null
+This package was debianized by martin f. krafft <madduck@debian.org> on
+Mon, 11 Aug 2008 17:32:48 -0300.
+
+It was downloaded from <http://repo.or.cz/w/topgit.git>
+
+Upstream Author:
+
+ Petr Baudis <pasky@suse.cz>
+
+Copyright:
+
+ Copyright © 2008 Petr Baudis <pasky@suse.cz>
+
+License:
+
+ This package is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License version 2 as
+ published by the Free Software Foundation.
+
+ This package is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this package; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+On Debian systems, the complete text of the GNU General
+Public License v2 can be found in `/usr/share/common-licenses/GPL-2'.
+
+The Debian packaging is (C) 2008-9, martin f. krafft <madduck@debian.org> and
+is licensed under the GPLv2, see above.
--- /dev/null
+#!/usr/bin/make -f
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+
+TG_BRANCHES="fixes/ensure-worktree debian/locations"
+
+include /usr/share/quilt/quilt.make
+include debian/tg2quilt.mk
+
+build: build-stamp
+build-stamp: patch
+ dh_testdir
+ $(MAKE) prefix=/usr
+ touch $@
+
+clean: unpatch
+ dh_testdir
+ dh_testroot
+ rm -f build-stamp
+ $(MAKE) clean
+ dh_clean
+
+install: build
+ dh_testdir
+ dh_testroot
+ dh_clean -k
+ dh_installdirs
+ $(MAKE) DESTDIR=$(CURDIR)/debian/topgit prefix=/usr install
+ rm -f $(wildcard $(CURDIR)/debian/topgit/usr/share/topgit/*.txt)
+ dh_install
+ install -m644 contrib/tg-completion.bash debian/topgit/etc/bash_completion.d/topgit
+
+
+binary-arch: build install
+binary-indep: build install
+ dh_testdir
+ dh_testroot
+ dh_installchangelogs
+ dh_installdocs
+ dh_compress
+ dh_fixperms
+ dh_installdeb
+ dh_gencontrol
+ dh_md5sums
+ dh_builddeb
+
+binary: binary-indep binary-arch
+.PHONY: build clean binary-indep binary-arch binary install configure
--- /dev/null
+#
+# tg2quilt.mk - TopGit-to-quilt functionality for debian/rules files
+#
+# This make(1) snippet facilitates the conversion of TopGit branches to
+# a quilt series.
+#
+# It is intended to be included from debian/rules files of TopGit-using
+# packages after including the quilt rules, like so:
+#
+# include /usr/share/quilt/quilt.make
+# -include /usr/share/topgit/tg2quilt.mk
+#
+# The leading dash is necessary for make not to die when the file is not
+# installed. TopGit is not a build dependency (and does not need to be), and
+# if the package is not installed, debian/rules can still be used normally.
+#
+# The snippet exports the following targets. These targets only perform the
+# describe behaviour when invoked from a TopGit repository (`tg summary -t`
+# returns a non-empty set); used outside, they simply output informational
+# messages but do not cause errors.
+#
+# tg-export: exports the TopGit patches into a quilt series under
+# debian/patches.
+# You may set TG_BRANCHES to a comma- or -space-separated
+# subset of branches (but not comma-and-space-separated) to
+# export (before including the file).
+# If debian/patches/series already exists, the target
+# will take note, blather a bit, and get out of the way.
+#
+# tg-clean: cleans the source tree, just like the debian/rules clean
+# target, and invokes tg-rmdir
+#
+# tg-rmdir: tries to remove debian/patches, but only if there are no
+# non-TopGit files under the directory.
+# The heuristic is to find files that do not contain a line
+# matchines /^tg:/, minus the series file. If any such files
+# are found, an error occurs. Otherwise, the directory is
+# removed. This means that edits to the series file are
+# likely to vanish.
+#
+# tg-cleanexport: recreates the debian/patches directory from scratch, using
+# tg-rmdir and tg-export.
+#
+# tg-forceclean: cleans the source tree, just like the debian/rules clean
+# target, and forcefully removes the debian/patches
+# directory in doing so. Yes, *force*-fully. WHAM!
+#
+# This file also hooks into the standard debian/rules and quilt targets such
+# that tg-export is automatically invoked before quilt gets a chance to patch
+# or unpatch the tree.
+#
+# The QUILT_PATCH_DIR variable can be set before including the file to override
+# the default debian/patches location.
+#
+# More information, particularly for people working on TopGit-using packages,
+# can be found in /usr/share/doc/topgit/HOWTO-tg2quilt.gz .
+#
+# Copyright © 2008 martin f. krafft <madduck@debian.org> Released under terms
+# of the the Artistic Licence 2.0.
+#
+
+ifeq ($(shell tg summary -t),)
+ # This is not a TopGit branch, so just blubber a bit.
+
+ tg-export tg-clean tg-forceclean tg-rmdir tg-cleanexport:
+ @echo "E: The $@ target only works from a TopGit repository." >&2
+else
+
+# We are in a TopGit branch, so let the fun begin.
+
+ifdef PATCHES_DIR
+ DUMMY := $(warning W: The $$PATCHES_DIR variable is deprecated, please use $$QUILT_PATCH_DIR instead.)
+ DUMMY := $(warning W: Sleeping for 10 seconds so you can read this!)
+ DUMMY := $(shell sleep 10)
+ QUILT_PATCH_DIR := $(PATCHES_DIR)
+endif
+
+# Hook tg-export into quilt's make(1) snippet such that it gets executed
+# before quilt patches or unpatches.
+$(QUILT_STAMPFN): tg-export
+unpatch: __tg-temp-export
+__tg-temp-export:
+ @echo "Exporting TopGit branches to series so that quilt can clean up..." >&2
+ $(MAKE) --no-print-directory -f debian/rules tg-export
+.PHONY: __tg-temp-export
+
+# Set some tg-export-specific variables, e.g. default TG_BRANCHES to all
+# TopGit branches
+tg-export: TG_BRANCHES ?= $(shell tg summary -t)
+ # see make manual for this trick:
+tg-export: __TG_COMMA := ,
+tg-export: __TG_EMPTY :=
+tg-export: __TG_SPACE := $(__TG_EMPTY) $(__TG_EMPTY)
+
+ifeq ($(wildcard $(QUILT_PATCH_DIR)/series),)
+ # The series file does not exist, so we proceed normally
+
+ # tg-export will not work if the target dir already exists, so try to remove
+ # it by calling tg-rmdir
+ tg-export: tg-rmdir
+ tg export -b $(subst $(__TG_SPACE),$(__TG_COMMA),$(TG_BRANCHES)) --quilt $(QUILT_PATCH_DIR)
+else
+ # The series file already exists, so assume there is nothing to do.
+ tg-export:
+ @echo "I: TopGit patch series already exists, nothing to do." >&2
+ @echo "I: (invoke the \`tg-clean\` target to remove the series.)" >&2
+ @echo "I: (you can ignore this message during a \`tg-clean\` run.)" >&2
+endif
+
+ifeq ($(wildcard $(QUILT_PATCH_DIR)),)
+ # No patch directory, so nothing to do:
+ tg-rmdir:
+ @true
+
+else
+ # There is a patch directory, let's try to clean it out:
+ tg-rmdir: __TG_FILES := $(shell find $(QUILT_PATCH_DIR) -type f -a -not -path \*/series \
+ | xargs grep -l '^tg:')
+ tg-rmdir:
+ # remove all files whose contents matches /^tg:/
+ test -n "$(__TG_FILES)" && rm $(__TG_FILES) || :
+ # remove the series file
+ test -f $(QUILT_PATCH_DIR)/series && rm $(QUILT_PATCH_DIR)/series || :
+ # try to remove directories
+ find $(QUILT_PATCH_DIR) -depth -type d -empty -execdir rmdir {} +
+ # fail if the directory could not be removed and still exists
+ @test ! -d $(QUILT_PATCH_DIR) || { \
+ echo "E: $(QUILT_PATCH_DIR) contains non-TopGit-generated files:" >&2; \
+ find $(QUILT_PATCH_DIR) -type f -printf 'E: %P\n' >&2; \
+ false; \
+ }
+endif
+
+# Make sure that we try to clean up the patches directory last
+tg-clean: clean
+ $(MAKE) --no-print-directory -f debian/rules tg-rmdir
+
+tg-forceclean: clean
+ test -d $(QUILT_PATCH_DIR) && rm -r $(QUILT_PATCH_DIR) || :
+
+tg-cleanexport: tg-rmdir
+ $(MAKE) --no-print-directory -f debian/rules tg-export
+
+endif
+
+.PHONY: tg-clean tg-export tg-forceclean tg-rmdir
+
+# vim:ft=make:ts=8:noet
+# -*- Makefile -*-, you silly Emacs! (shamelessly stolen from quilt)
--- /dev/null
+etc/bash_completion.d
+usr/bin
+usr/share/topgit
--- /dev/null
+README
+debian/README.source
+debian/HOWTO-tg2quilt
--- /dev/null
+debian/tg2quilt.mk usr/share/topgit
--- /dev/null
+tg-export: TG_BRANCHES ?= $(shell tg summary -t)
+tg-export: __TG_SUBST_COMMA := ,
+tg-export: __TG_SUBST_EMPTY :=
+tg-export: __TG_SUBST_SPACE := $(__TG_SUBST_EMPTY) $(__TG_SUBST_EMPTY)
+tg-export:
+ test -d debian/patches && rm -r debian/patches || :
+ tg export -b $(subst $(__TG_SUBST_SPACE),$(__TG_SUBST_COMMA),$(TG_BRANCHES)) --quilt debian/patches
+.PHONY: tg-export