Stefano Zacchiroli wrote: > On Tue, Aug 04, 2009 at 01:49:58AM +0200, Franck Joncourt wrote: >>>> --- /dev/null +++ b/debian/topgit.manpages @@ -0,0 +1,10 @@ >>>> +tg-create.1 +tg-delete.1 +tg-depend.1 +tg-import.1 +tg-info.1 >>>> +tg-mail.1 +tg-patch.1 +tg-remote.1 +tg-summary.1 +tg-update.1 >>> What about autogenerating this file? >> It sounds a bit strange to me to generate debhelper files >> automatically, but why not :) > > Most of debhelpers support globbing in their configuration files. As > long as you generate all manpages in predictable places, a *.1 should > do the trick without adding the burden of autogeneration. > Disclaimer: I haven't tried if dh_installmanpages actually supports > globbing or not, but is worth trying/checking.
I have always used dh_installman so far, and not dh_installmanpages. I remembered they were two debhelpers to handle the man pages, but the wrong one caught my attention first :) Patches are enclosed. I have left the txt files in /usr/share/doc/topgit/ since it looks like they are used by tg in a *help mode*. I also wonder if this is still useful to keep the README file in /usr/share/doc/topgit, since it contains only the manpages and nothing more at the moment. Regards, -- Franck Joncourt http://debian.org - http://smhteam.info/wiki/
From: Franck Joncourt <franck.m...@dthconnex.com> Subject: [PATCH] t/debian/manpages Created manpages for the tg commands from the their documentation (txt files) using asciidoc. Signed-off-by: Franck Joncourt <franck.m...@dthconnex.com> --- debian/control | 1 + debian/rules | 12 +++++++++++- debian/topgit.manpages | 1 + 3 files changed, 13 insertions(+), 1 deletions(-) diff --git a/debian/control b/debian/control index 35f6761..596e71a 100644 --- a/debian/control +++ b/debian/control @@ -4,6 +4,7 @@ Priority: optional Maintainer: Debian TopGit maintainers <pkg-top...@teams.debian.net> Uploaders: martin f. krafft <madd...@debian.org>, Uwe Kleine-König <u.kleine-koe...@pengutronix.de> Build-Depends: debhelper (>= 6), quilt +Build-Depends-Indep: asciidoc, xmlto Standards-Version: 3.8.0 Homepage: http://repo.or.cz/w/topgit.git Vcs-Git: git://git.debian.org/git/collab-maint/topgit.git diff --git a/debian/rules b/debian/rules index 712fcae..37c6f42 100755 --- a/debian/rules +++ b/debian/rules @@ -5,19 +5,28 @@ TG_BRANCHES="fixes/ensure-worktree debian/locations" +TG_MANS := $(patsubst %.sh,%.1,$(wildcard tg*.sh)) + include /usr/share/quilt/quilt.make include debian/tg2quilt.mk -build: build-stamp +build: build-stamp $(TG_MANS) build-stamp: patch dh_testdir $(MAKE) prefix=/usr touch $@ +$(TG_MANS): + @TXT_FILE=`echo $@ | sed -e 's/1/txt/'` && \ + echo -n 'Creating manpage $@ ...' && \ + /usr/bin/a2x -Lf manpage $$TXT_FILE 2>/dev/null && \ + echo 'Done' + clean: unpatch dh_testdir dh_testroot rm -f build-stamp + rm -f $(TG_MANS) *.xml $(MAKE) clean dh_clean @@ -37,6 +46,7 @@ binary-indep: build install dh_testdir dh_testroot dh_installchangelogs + dh_installman dh_installdocs dh_compress dh_fixperms diff --git a/debian/topgit.manpages b/debian/topgit.manpages new file mode 100644 index 0000000..8dff2f9 --- /dev/null +++ b/debian/topgit.manpages @@ -0,0 +1 @@ +tg*.1 -- tg: (3aebd65..) t/debian/manpages (depends on: debian)
From: Franck Joncourt <franck.m...@dthconnex.com>
Subject: [PATCH] t/upstream/manpages
This is an attempt to create manpages for the tg commands from the README file
usptream ships. This one has been updated so that information on the tg-command
could be converted by asciidoc.
Signed-off-by: Franck Joncourt <franck.m...@dthconnex.com>
---
Makefile | 6 +-
README | 1219 ++++++++++++++++++++++++++++++++++++--------------------
create-help.sh | 10 +-
3 files changed, 797 insertions(+), 438 deletions(-)
diff --git a/Makefile b/Makefile
index 3ce39a5..0d9659d 100644
--- a/Makefile
+++ b/Makefile
@@ -10,9 +10,9 @@ hooks_in = hooks/pre-commit.sh
commands_out := $(patsubst %.sh,%,$(commands_in))
hooks_out := $(patsubst %.sh,%,$(hooks_in))
-help_out := $(patsubst %.sh,%.txt,$(commands_in))
+help_out := $(patsubst %.sh,%.txt,$(wildcard tg*.sh))
-all:: tg $(commands_out) $(hooks_out) $(help_out)
+all:: $(help_out) tg $(commands_out) $(hooks_out)
tg $(commands_out) $(hooks_out): % : %.sh Makefile
@echo "[SED] $@"
@@ -25,7 +25,7 @@ tg $(commands_out) $(hooks_out): % : %.sh Makefile
mv $...@+ $@
$(help_out): README
- @CMD=`echo $@ | sed -e 's/tg-//' -e 's/\.txt//'` && \
+ @CMD=`echo $@ | sed -e 's/\.txt//'` && \
echo '[HELP]' $$CMD && \
./create-help.sh $$CMD
diff --git a/README b/README
index d2f095d..437cb76 100644
--- a/README
+++ b/README
@@ -1,9 +1,148 @@
-TopGit - A different patch queue manager
+TG(1)
+=====
+
+NAME
+----
+tg - a different patch queue manager
+
+SYNOPSIS
+--------
+
+ ## Create and evolve a topic branch
+ $ tg create t/gitweb/pathinfo-action
+ tg: Automatically marking dependency on master
+ tg: Creating t/gitweb/pathinfo-action base from master...
+ $ ..hack..
+ $ git commit
+ $ ..fix a mistake..
+ $ git commit
+
+ ## Create another topic branch on top of the former one
+ $ tg create t/gitweb/nifty-links
+ tg: Automatically marking dependency on t/gitweb/pathinfo-action
+ tg: Creating t/gitweb/nifty-links base from t/gitweb/pathinfo-action...
+ $ ..hack..
+ $ git commit
+
+ ## Create another topic branch on top of master and submit
+ ## the resulting patch upstream
+ $ tg create t/revlist/author-fixed master
+ tg: Creating t/revlist/author-fixed base from master...
+ $ ..hack..
+ $ git commit
+ $ tg patch -m
+ tg: Sent t/revlist/author-fixed
+ From: pa...@suse.cz
+ To: g...@vger.kernel.org
+ Cc: gits...@pobox.com
+ Subject: [PATCH] Fix broken revlist --author when --fixed-string
+
+ ## Create another topic branch depending on two others non-trivially
+ $ tg create t/whatever t/revlist/author-fixed t/gitweb/nifty-links
+ tg: Creating t/whatever base from t/revlist/author-fixed...
+ tg: Merging t/whatever base with t/gitweb/nifty-links...
+ Merge failed!
+ tg: Please commit merge resolution and call: tg create
+ tg: It is also safe to abort this operation using `git reset --hard`
+ tg: but please remember you are on the base branch now;
+ tg: you will want to switch to a different branch.
+ $ ..resolve..
+ $ git commit
+ $ tg create
+ tg: Resuming t/whatever setup...
+ $ ..hack..
+ $ git commit
+
+ ## Update a single topic branch and propagate the changes to
+ ## a different one
+ $ git checkout t/gitweb/nifty-links
+ $ ..hack..
+ $ git commit
+ $ git checkout t/whatever
+ $ tg info
+ Topic Branch: t/whatever (1 commit)
+ Subject: [PATCH] Whatever patch
+ Base: 3f47ebc1
+ Depends: t/revlist/author-fixed t/gitweb/nifty-links
+ Needs update from:
+ t/gitweb/nifty-links (1 commit)
+ $ tg update
+ tg: Updating base with t/gitweb/nifty-links changes...
+ Merge failed!
+ tg: Please commit merge resolution and call `tg update` again.
+ tg: It is also safe to abort this operation using `git reset --hard`,
+ tg: but please remember you are on the base branch now;
+ tg: you will want to switch to a different branch.
+ $ ..resolve..
+ $ git commit
+ $ tg update
+ tg: Updating t/whatever against new base...
+ Merge failed!
+ tg: Please resolve the merge and commit. No need to do anything else.
+ tg: You can abort this operation using `git reset --hard` now
+ tg: and retry this merge later using `tg update`.
+ $ ..resolve..
+ $ git commit
+
+ ## Update a single topic branch and propagate the changes
+ ## further through the dependency chain
+ $ git checkout t/gitweb/pathinfo-action
+ $ ..hack..
+ $ git commit
+ $ git checkout t/whatever
+ $ tg info
+ Topic Branch: t/whatever (1/2 commits)
+ Subject: [PATCH] Whatever patch
+ Base: 0ab2c9b3
+ Depends: t/revlist/author-fixed t/gitweb/nifty-links
+ Needs update from:
+ t/gitweb/pathinfo-action (<= t/gitweb/nifty-links) (1 commit)
+ $ tg update
+ tg: Recursing to t/gitweb/nifty-links...
+ [t/gitweb/nifty-links] tg: Updating base with t/gitweb/pathinfo-action changes...
+ Merge failed!
+ [t/gitweb/nifty-links] tg: Please commit merge resolution and call `tg update` again.
+ [t/gitweb/nifty-links] tg: It is also safe to abort this operation using `git reset --hard`,
+ [t/gitweb/nifty-links] tg: but please remember you are on the base branch now;
+ [t/gitweb/nifty-links] tg: you will want to switch to a different branch.
+ [t/gitweb/nifty-links] tg: You are in a subshell. If you abort the merge,
+ [t/gitweb/nifty-links] tg: use `exit` to abort the recursive update altogether.
+ [t/gitweb/nifty-links] $ ..resolve..
+ [t/gitweb/nifty-links] $ git commit
+ [t/gitweb/nifty-links] $ tg update
+ [t/gitweb/nifty-links] tg: Updating t/gitweb/nifty-links against new base...
+ Merge failed!
+ [t/gitweb/nifty-links] tg: Please resolve the merge and commit.
+ [t/gitweb/nifty-links] tg: You can abort this operation using `git reset --hard`.
+ [t/gitweb/nifty-links] tg: You are in a subshell. After you either commit or abort
+ [t/gitweb/nifty-links] tg: your merge, use `exit` to proceed with the recursive update.
+ [t/gitweb/nifty-links] $ ..resolve..
+ [t/gitweb/nifty-links] $ git commit
+ [t/gitweb/nifty-links] $ exit
+ tg: Updating base with t/gitweb/nifty-links changes...
+ tg: Updating t/whatever against new base...
+
+ ## Clone a TopGit-controlled repository
+ $ git clone URL repo
+ $ cd repo
+ $ tg remote --populate origin
+ ...
+ $ git fetch
+ $ tg update
+
+ ## Add a TopGit remote to a repository and push to it
+ $ git remote add foo URL
+ $ tg remote foo
+ $ git push foo
+
+ ## Update from a non-default TopGit remote
+ $ git fetch foo
+ $ tg -r foo summary
+ $ tg -r foo update
DESCRIPTION
-----------
-
TopGit aims to make handling of large amount of interdependent topic
branches easier. In fact, it is designed especially for the case
when you maintain a queue of third-party patches on top of another
@@ -11,10 +150,8 @@ when you maintain a queue of third-party patches on top of another
and submit them - TopGit achieves that by keeping a separate topic
branch for each patch and providing few tools to maintain the branches.
-
RATIONALE
---------
-
Why not use something like StGIT or Guilt or rebase -i for maintaining
your patch queue? The advantage of these tools is their simplicity;
they work with patch _series_ and defer to the reflog facility for
@@ -27,18 +164,18 @@ these tools horribly fail in the face of distributed environment.
TopGit has been designed around three main tenets:
- (i) TopGit is as thin layer on top of Git as possible.
+ (i) TopGit is as thin layer on top of Git as possible.
You still maintain your index and commit using Git, TopGit will
only automate few indispensable tasks.
- (ii) TopGit is anxious about _keeping_ your history. It will
+ (ii) TopGit is anxious about _keeping_ your history. It will
never rewrite your history and all metadata is also tracked by Git,
smoothly and non-obnoxiously. It is good to have a _single_ point
when the history is cleaned up, and that is at the point of inclusion
in the upstream project; locally, you can see how your patch has evolved
and easily return to older versions.
- (iii) TopGit is specifically designed to work in distributed
+ (iii) TopGit is specifically designed to work in distributed
environment. You can have several instances of TopGit-aware repositories
and smoothly keep them all up-to-date and transfer your changes between
them.
@@ -59,429 +196,28 @@ called a _base_ of the patch (topic branch).
Of course, TopGit is perhaps not the right tool for you:
- (i) TopGit is not complicated, but StGIT et al. are somewhat
+ (i) TopGit is not complicated, but StGIT et al. are somewhat
simpler, conceptually. If you just want to make a linear purely-local
patch queue, deferring to StGIT instead might make more sense.
- (ii) When using TopGit, your history can get a little hairy
+ (ii) When using TopGit, your history can get a little hairy
over time, especially with all the merges rippling through. ;-)
-
-SYNOPSIS
---------
-
- ## Create and evolve a topic branch
- $ tg create t/gitweb/pathinfo-action
- tg: Automatically marking dependency on master
- tg: Creating t/gitweb/pathinfo-action base from master...
- $ ..hack..
- $ git commit
- $ ..fix a mistake..
- $ git commit
-
- ## Create another topic branch on top of the former one
- $ tg create t/gitweb/nifty-links
- tg: Automatically marking dependency on t/gitweb/pathinfo-action
- tg: Creating t/gitweb/nifty-links base from t/gitweb/pathinfo-action...
- $ ..hack..
- $ git commit
-
- ## Create another topic branch on top of master and submit
- ## the resulting patch upstream
- $ tg create t/revlist/author-fixed master
- tg: Creating t/revlist/author-fixed base from master...
- $ ..hack..
- $ git commit
- $ tg patch -m
- tg: Sent t/revlist/author-fixed
- From: pa...@suse.cz
- To: g...@vger.kernel.org
- Cc: gits...@pobox.com
- Subject: [PATCH] Fix broken revlist --author when --fixed-string
-
- ## Create another topic branch depending on two others non-trivially
- $ tg create t/whatever t/revlist/author-fixed t/gitweb/nifty-links
- tg: Creating t/whatever base from t/revlist/author-fixed...
- tg: Merging t/whatever base with t/gitweb/nifty-links...
- Merge failed!
- tg: Please commit merge resolution and call: tg create
- tg: It is also safe to abort this operation using `git reset --hard`
- tg: but please remember you are on the base branch now;
- tg: you will want to switch to a different branch.
- $ ..resolve..
- $ git commit
- $ tg create
- tg: Resuming t/whatever setup...
- $ ..hack..
- $ git commit
-
- ## Update a single topic branch and propagate the changes to
- ## a different one
- $ git checkout t/gitweb/nifty-links
- $ ..hack..
- $ git commit
- $ git checkout t/whatever
- $ tg info
- Topic Branch: t/whatever (1 commit)
- Subject: [PATCH] Whatever patch
- Base: 3f47ebc1
- Depends: t/revlist/author-fixed t/gitweb/nifty-links
- Needs update from:
- t/gitweb/nifty-links (1 commit)
- $ tg update
- tg: Updating base with t/gitweb/nifty-links changes...
- Merge failed!
- tg: Please commit merge resolution and call `tg update` again.
- tg: It is also safe to abort this operation using `git reset --hard`,
- tg: but please remember you are on the base branch now;
- tg: you will want to switch to a different branch.
- $ ..resolve..
- $ git commit
- $ tg update
- tg: Updating t/whatever against new base...
- Merge failed!
- tg: Please resolve the merge and commit. No need to do anything else.
- tg: You can abort this operation using `git reset --hard` now
- tg: and retry this merge later using `tg update`.
- $ ..resolve..
- $ git commit
-
- ## Update a single topic branch and propagate the changes
- ## further through the dependency chain
- $ git checkout t/gitweb/pathinfo-action
- $ ..hack..
- $ git commit
- $ git checkout t/whatever
- $ tg info
- Topic Branch: t/whatever (1/2 commits)
- Subject: [PATCH] Whatever patch
- Base: 0ab2c9b3
- Depends: t/revlist/author-fixed t/gitweb/nifty-links
- Needs update from:
- t/gitweb/pathinfo-action (<= t/gitweb/nifty-links) (1 commit)
- $ tg update
- tg: Recursing to t/gitweb/nifty-links...
- [t/gitweb/nifty-links] tg: Updating base with t/gitweb/pathinfo-action changes...
- Merge failed!
- [t/gitweb/nifty-links] tg: Please commit merge resolution and call `tg update` again.
- [t/gitweb/nifty-links] tg: It is also safe to abort this operation using `git reset --hard`,
- [t/gitweb/nifty-links] tg: but please remember you are on the base branch now;
- [t/gitweb/nifty-links] tg: you will want to switch to a different branch.
- [t/gitweb/nifty-links] tg: You are in a subshell. If you abort the merge,
- [t/gitweb/nifty-links] tg: use `exit` to abort the recursive update altogether.
- [t/gitweb/nifty-links] $ ..resolve..
- [t/gitweb/nifty-links] $ git commit
- [t/gitweb/nifty-links] $ tg update
- [t/gitweb/nifty-links] tg: Updating t/gitweb/nifty-links against new base...
- Merge failed!
- [t/gitweb/nifty-links] tg: Please resolve the merge and commit.
- [t/gitweb/nifty-links] tg: You can abort this operation using `git reset --hard`.
- [t/gitweb/nifty-links] tg: You are in a subshell. After you either commit or abort
- [t/gitweb/nifty-links] tg: your merge, use `exit` to proceed with the recursive update.
- [t/gitweb/nifty-links] $ ..resolve..
- [t/gitweb/nifty-links] $ git commit
- [t/gitweb/nifty-links] $ exit
- tg: Updating base with t/gitweb/nifty-links changes...
- tg: Updating t/whatever against new base...
-
- ## Clone a TopGit-controlled repository
- $ git clone URL repo
- $ cd repo
- $ tg remote --populate origin
- ...
- $ git fetch
- $ tg update
-
- ## Add a TopGit remote to a repository and push to it
- $ git remote add foo URL
- $ tg remote foo
- $ git push foo
-
- ## Update from a non-default TopGit remote
- $ git fetch foo
- $ tg -r foo summary
- $ tg -r foo update
-
-
USAGE
-----
-
The 'tg' tool of TopGit has several subcommands:
-tg help
-~~~~~~~
- Our sophisticated integrated help facility. Doesn't do
- a whole lot for now.
-
-tg create
-~~~~~~~~~
- Create a new TopGit-controlled topic branch of a given name
- (required argument) and switch to it. If no dependencies
- are specified (by extra arguments passed after the first one),
- the current branch is assumed to be the only dependency.
-
- After `tg create`, you should insert the patch description
- to the '.topmsg' file, which will already contain some
- prefilled bits. You can set topgit.to, topgit.cc and topgit.bcc
- configuration variables in order to have `tg create`
- add these headers with given default values to '.topmsg'.
-
- The main task of `tg create` is to set up the topic branch
- base from the dependencies. This may fail due to merge conflicts.
- In that case, after you commit the conflicts resolution,
- you should call `tg create` again (without any arguments);
- it will detect that you are on a topic branch base ref and
- resume the topic branch creation operation.
-
- In an alternative use case, if '-r BRANCH' is given instead
- of dependency list, the topic branch is created based on
- the given remote branch.
-
-tg delete
-~~~~~~~~~
- Remove a TopGit-controlled topic branch of given name
- (required argument). Normally, this command will remove
- only empty branch (base == head); use '-f' to remove
- non-empty branch.
-
- Currently, this command will _NOT_ remove the branch from
- the dependency list in other branches. You need to take
- care of this _manually_. This is even more complicated
- in combination with '-f', in that case you need to manually
- unmerge the removed branch's changes from the branches
- depending on it.
-
- TODO: '-a' to delete all empty branches, depfix, revert
-
-tg depend
-~~~~~~~~~
- Change dependencies of a TopGit-controlled topic branch.
- This should have several subcommands, but only 'add' is
- supported right now.
-
- The 'add' subcommand takes an argument of a topic branch
- to be added, adds it to '.topdeps', performs a commit and
- then updates your topic branch accordingly. If you want to
- do other things related to the dependency addition, like
- adjusting '.topmsg', prepare them in the index before
- calling 'tg depend add'.
-
- TODO: Subcommand for removing dependencies, obviously
-
-tg info
-~~~~~~~
- Show a summary information about the current or specified
- topic branch.
-
-tg patch
-~~~~~~~~
- Generate a patch from the current or specified topic branch.
- This means that the diff between the topic branch base and
- head (latest commit) is shown, appended to the description
- found in the .topmsg file.
-
- The patch is by default simply dumped to stdout. In the future,
- tg patch will be able to automatically send the patches by mail
- or save them to files. (TODO)
-
- Options:
- -i base patch generation on index instead of branch
- -w base patch generation on working tree instead of branch
-
-tg mail
-~~~~~~~
- Send a patch from the current or specified topic branch as
- email.
-
- Takes the patch given on the command line and emails it out.
- Destination addresses such as To, Cc and Bcc are taken from the
- patch header.
-
- Since it actually boils down to `git send-email` please refer to
- its documentation for details on how to setup email for git.
- You can pass arbitrary options to this command through the
- '-s' parameter, but you must double-quote everything.
- The '-r' parameter with msgid can be used to generate in-reply-to
- and reference headers to an earlier mail.
-
- TODO: 'tg mail patchfile' to mail an already exported patch
- TODO: mailing patch series
- TODO: specifying additional options and addresses on command
- line
-
-tg remote
-~~~~~~~~~
- Register given remote as TopGit-controlled. This will create
- the namespace for the remote branch bases and teach 'git fetch'
- and 'git push' to operate on them. (Do NOT use 'git push --all'
- for your pushes - plain 'git push' will do the right thing.)
-
- It takes a mandatory remote name argument, and optional
- '--populate' switch - use that for your origin-style remote,
- it will seed the local topic branch system based on the
- remote topic branches. '--populate' will also make 'tg remote'
- automatically fetch the remote and 'tg update' to look at
- branches of this remote for updates by default.
-
-tg summary
-~~~~~~~~~~
- Show overview of all TopGit-tracked topic branches and their
- up-to-date status ('>' marks the current topic branch,
- '0' marks that it introduces no own changes,
- 'l'/'r' marks that it is local-only or has remote mate,
- 'L'/'R' marks that it is ahead/out-of-date wrt. its remote mate,
- 'D' marks that it is out-of-date wrt. its dependencies,
- '!' marks that it has missing dependencies (even recursively),
- 'B' marks that it is out-of-date wrt. its base).
-
- This can take long time to accurately determine all the relevant
- information about each branch; you can pass '-t' to get just
- terse list of topic branch names quickly. Alternately, you can
- pass '--graphviz' to get a dot-suitable output to draw a dependency
- graph between the topic branches.
-
- TODO: Speed up by an order of magnitude
- TODO: Text graph view
-
-tg export
-~~~~~~~~~
- Export a tidied-up history of the current topic branch
- and its dependencies, suitable for feeding upstream.
- Each topic branch corresponds to a single commit or patch
- in the cleaned up history (corresponding basically exactly
- to `tg patch` output for the topic branch).
-
- The command has three possible outputs now - either a Git branch with
- the collapsed history, a Git branch with a linearized history, or a
- quilt series in new directory.
-
- In case of producing collapsed history in new branch,
- you can use this collapsed structure either for providing
- a pull source for upstream, or further linearization e.g.
- for creation of a quilt series using git log:
-
- git log --pretty=email -p --topo-order origin..exported
-
- To better understand the function of `tg export`,
- consider this dependency structure of topic branches:
-
- origin/master - t/foo/blue - t/foo/red - master
- `- t/bar/good <,----------'
- `- t/baz ------------'
-
- (Where each of the branches may have hefty history.) Then
-
- master$ tg export for-linus
-
- will create this commit structure on branch for-linus:
-
- origin/master - t/foo/blue -. merge - t/foo/red -.. merge - master
- `- t/bar/good <,-------------------'/
- `- t/baz ---------------------'
-
- In case of using the linearize mode:
-
- master$ tg export --linearize for-linus
-
- you get a linear history respecting the dependencies of your patches in
- a new branch for-linus. The result should be more or less the same as
- using quilt mode and reimporting it into a Git branch. (More or less
- because the topologic order can usually be extended in more than one
- way into a complete ordering and the two methods may choose different
- one's.) The result might be more appropriate for merging upstream as
- it contains fewer merges.
-
- Note that you might get conflicts during linearization because the
- patches are reordered to get a linear history.
-
- In case of the quilt mode,
-
- master$ tg export --quilt for-linus
-
- would create this directory for-linus:
-
- for-linus/t/foo/blue.diff
- for-linus/t/foo/red.diff
- for-linus/t/bar/good.diff
- for-linus/t/baz.diff
- for-linus/series:
- t/foo/blue.diff -p1
- t/bar/good.diff -p1
- t/foo/red.diff -p1
- t/baz.diff -p1
-
- The command works on the current topic branch
- and can be called either without a parameter
- (in that case, '--collapse' is assumed)
- and with one mandatory argument: the name of the branch
- where the exported result shall be stored.
- The branch will be silently overwritten if it exists already!
- Use git reflog to recover in case of mistake.
-
- Alternatively, call it with the '--quilt' parameter
- and an argument specifying the directory
- where the quilt series should be saved.
-
- With '--quilt', you can also pass '-b' parameter followed by
- a comma-separated explicit list of branches to export. This
- mode of operation is currently not supported with collapse.
-
- In '--quilt' mode the patches are named like the originating topgit
- branch. So usually they end up in subdirectories of the output
- directory. With option '--flatten' the names are mangled such that
- they end up directly in the output dir (i.e. slashed are substituted by
- underscores). With '--numbered' (which implies '--flatten') the patch
- names get a number as prefix to allow getting the order without
- consulting the series file, which eases sending out the patches.
-
- Usage: tg export ([(--collapse | --linearize)] BRANCH | --quilt DIR)
-
- TODO: Make stripping of non-essential headers configurable
- TODO: Make stripping of [PATCH] and other prefixes configurable
- TODO: --mbox option for other mode of operation
- TODO: -a option to export all branches
- TODO: For quilt exporting, export the linearized history created in a
- temporary branch---this would allow producing conflict-less
- series
-
-tg import
-~~~~~~~~~
- Import commits within the given revision range into TopGit,
- creating one topic branch per commit, the dependencies forming
- a linear sequence starting on your current branch (or a branch
- specified by the '-d' parameter).
-
- The branch names are auto-guessed from the commit messages
- and prefixed by t/ by default; use '-p PREFIX' to specify
- an alternative prefix (even an empty one).
-
- Alternatively, you can use the '-s NAME' parameter to specify
- the name of target branch; the command will then take one more
- argument describing a single commit to import.
-
-tg update
-~~~~~~~~~
- Update the current topic branch wrt. changes in the branches
- it depends on and remote branches.
- This is performed in two phases - first,
- changes within the dependencies are merged to the base,
- then the base is merged into the topic branch.
- The output will guide you in case of conflicts.
-
- In case your dependencies are not up-to-date, tg update
- will first recurse into them and update these.
-
- If a remote branch update brings dependencies on branches
- not yet instantiated locally, you can either bring in all
- the new branches from the remote using 'tg remote --populate'
- or only pick out the missing ones using 'tg create -r'
- ('tg summary' will point out branches with incomplete
- dependencies by showing an '!' near to them).
-
- TODO: tg update -a for updating all topic branches
-
-TODO: tg rename
-
+ tg-create: create a new TopGit branch
+ tg-delete: remove a TopGit topic branch
+ tg-depend: update dependencies of a TopGit branch
+ tg-export: export history of a TopGit topic branch
+ tg-import: import commits into a TopGit topic branch
+ tg-info: display summary of a TopGit branch
+ tg-mail: send a patch from a TopGit branch by email
+ tg-patch: generate a patch from a TopGit branch
+ tg-remote: register a remote branch as a TopGit topic branch
+ tg-summary: display an overview of all TopGit branches
+ tg-update: update a TopGit branch
IMPLEMENTATION
--------------
@@ -503,7 +239,7 @@ and are of course omitted during `tg patch`. The state of these
files in base commits is undefined; look at them only in the topic
branches themselves. Currently, two files are defined:
- .topmsg: Contains the description of the topic branch
+ .topmsg: Contains the description of the topic branch
in a mail-like format, plus the author information,
whatever Cc headers you choose or the post-three-dashes message.
When mailing out your patch, basically only few extra headers
@@ -514,7 +250,7 @@ versa and similar nuances, if your project is into that.
From is prefilled from your current GIT_AUTHOR_IDENT, other headers
can be prefilled from various optional topgit.* config options.
- .topdeps: Contains the one-per-line list of branches
+ .topdeps: Contains the one-per-line list of branches
your patch depends on, pre-seeded with `tg create`. (Continuously
updated) merge of these branches will be the "base" of your topic
branch. DO NOT EDIT THIS FILE MANUALLY!!! If you do so, you need
@@ -533,15 +269,14 @@ Another automagically installed piece is .git/info/attributes specifier
for an 'ours' merge strategy for the files .topmsg and .topdeps, and
the (intuitive) 'ours' merge strategy definition in .git/config.
-
REMOTE HANDLING
---------------
There are three issues with accessing topic branches in remote repositories:
- (i) Fetching/pushing accurate picture of the remote topic branch setup
- (ii) Referring to remote topic branches from your local repository
- (iii) Developing some of the remote topic branches locally
+ (i) Fetching/pushing accurate picture of the remote topic branch setup
+ (ii) Referring to remote topic branches from your local repository
+ (iii) Developing some of the remote topic branches locally
(ii) and (iii) are fairly interconnected problems, while (i) is largely
independent. The issue is to accurately reflect the current state of the
@@ -555,9 +290,9 @@ command to set up an existing remote for TopGit usage.
About (ii) and (iii), there are two somewhat contradicting design
considerations:
- (a) Hacking on multiple independent TopGit remotes in a single
- repository
- (b) Having a self-contained topic system in local refs space
+ (a) Hacking on multiple independent TopGit remotes in a single
+ repository
+ (b) Having a self-contained topic system in local refs space
To us, (a) does not appear to be very convincing, while (b) is quite desirable
for 'git-log topic' etc. working, 'git push' automatically creating
@@ -579,3 +314,627 @@ All commands by default refer to the remote that 'tg remote --populate'
was called on the last time ('topgit.remote' configuration variable). You can
manually run any command with a different base remote by passing '-r REMOTE'
_before_ the subcommand name.
+
+SEE-ALSO
+--------
+tg-create(1), tg-delete(1), tg-depend(1), tg-export(1), tg-import(1),
+tg-info(1), tg-mail(1), tg-patch(1), tg-remote(1), tg-summary(1), tg-update(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-CREATE(1)
+===========
+
+NAME
+----
+tg-create - create a new TopGit branch
+
+SYNOPSIS
+--------
+*tg create* 'NAME' ['DEPS...' | '-r RNAME']
+
+DESCRIPTION
+-----------
+The tg-create command is part of the topgit's tools suite.
+
+It creates a new TopGit-controlled topic branch from a list of dependencies,
+and switching to it.
+
+The *NAME* argument is the name of the branch to be created, and a list
+of dependencies must be specified as a space-separated list unless a remote
+branch is specified using *-r*.
+
+Setting up the topic branch may fail due to merge conflicts. In that case,
+after you commit the conflicts resolution, you should call *tg create* again
+(without any arguments); it will detect that you are on a topic branch base ref
+and resume the topic branch creation operation.
+
+After *tg create*, you should insert the patch description to the *.topmsg*
+file, which will already contain some prefilled bits.
+
+OPTIONS
+-------
+*-r RNAME*::
+Specify a remote branch instead of a dependency list on which to base the
+topic branch.
+
+FILES
+-----
+*.topmsg*::
+This file is intended to contains the author name and a short and long
+description of the topic branch. More fields can automatically be added by
+setting some git variables (see section VARIABLES).
+*.topdeps*::
+List the dependencies the topic branch is based on.
+
+VARIABLES
+---------
+The user can tell *tg-create* to append more fields to the *.topmsg* file. Three
+variables are available:
+
+*topgit.to*::
+Append a *TO* header.
+*topgit.cc*::
+Append a *CC* header.
+*topgit.bcc*::
+Append a *BCC* header.
+
+Thus, if we use:
+
+$ git config --add u...@example.com topgit.to
+
+A *TO* header will be added to *.topmsg* when creating the topic branch.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-DELETE(1)
+===========
+
+NAME
+----
+tg-delete - removes a TopGit topic branch
+
+SYNOPSIS
+--------
+*tg delete* ['-f'] 'NAME'
+
+DESCRIPTION
+-----------
+The tg-delete command is part of the topgit's tool suite.
+
+It removes an empty topgit branch specified by the *NAME* argument. Currently,
+this command will _NOT_ remove the branch from the dependency list in other
+branches. You need to take
+
+OPTIONS
+-------
+*-f*::
+Force to remove a non empty branch (base != head). You will have to manually
+unmerge the removed branch's changes from the branches depending on it.
+
+TODOS
+-----
+Add a *-a* option to delete all empty branches, depfix, revert.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-DEPEND(1)
+===========
+
+NAME
+----
+tg-depend - update dependencies of a TopGit branch
+
+SYNOPSIS
+--------
+*tg depend* add 'NAME'
+
+DESCRIPTION
+-----------
+The tg-depend command is part of the topgit's tools suite.
+
+It allows the user to update the list of dependencies of the topic branch.
+
+OPTIONS
+-------
+*add NAME*::
+Add a TopGit topic branch to *.todeps*, performs a commit and then update your
+topic branch accordingly.
+
+If you want to do other things related to the dependency addition, like
+adjusting *.topmsg*, prepare them in the index before calling *tg depend add*.
+
+TODOS
+-----
+Subcommand for removing dependencies, obviously
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-IMPORT(1)
+=============
+
+NAME
+----
+tg-import - import commits into a TopGit topic branch
+
+SYNOPSIS
+--------
+tg import ['-d BASE_BRANCH'] { ['-p PREFIX'] 'RANGE...' | '-s NAME COMMIT' }
+
+DESCRIPTION
+-----------
+The tg-import command is part of the topgit's tool suite.
+
+It imports commits within the given revision range into TopGit, creating one
+topic branch per commit, the dependencies forming a linear sequence starting
+on your current branch.
+
+The branch names are auto-guessed from the commit messages and prefixed by t/.
+
+Alternatively, you can use the '-s NAME' parameter to specify
+the name of target branch; the command will then take one more
+argument describing a single commit to import.
+
+
+OPTIONS
+-------
+*-d base_branch*::
+Specify the branch to import commits from. By default, the current branch is
+used.
+
+*-p prefix*::
+Specify an alternate prefix (even an empty one).
+
+*-s name commit*::
+Import a single 'commit' into a new TopGit topic branch known as 'name'.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-INFO(1)
+===========
+
+NAME
+----
+tg-info - display summary of a TopGit branch
+
+SYNOPSIS
+--------
+*tg info* ['NAME']
+
+DESCRIPTION
+-----------
+The tg-info command is part of the topgit's tools suite.
+
+It show information about the current branch unless a *NAME' is specified.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-MAIL(1)
+===========
+
+NAME
+----
+tg-mail - send a patch from a TopGit branch by email
+
+SYNOPSIS
+--------
+*tg mail* ['-s SEND_EMAIL_ARGS'] ['-r REFERENCE_MSGID'] ['NAME']
+
+DESCRIPTION
+-----------
+The tg-mail command is part of the topgit's tools suite.
+
+It sends a patch from the current or specified topic branch as
+email. Destination addresses such as To, Cc and Bcc are taken from the
+patch header.
+
+Since it actually boils down to *git send-email* please refer to its
+documentation for details on how to setup email for git.
+
+OPTIONS
+-------
+*-s SEND_EMAIL_ARGS*::
+Arguments to be passed to git-send-email. They must be double-quoted.
+
+*-r REFERENCE_MSGID*::
+Specify a reference msgid in order to generate in-reply-to and reference
+headers to an earlier mail.
+
+TODOS
+-----
+'tg mail patchfile' to mail an already exported patch
+
+mailing patch series
+
+specifying additional options and addresses on command line
+
+SEE-ALSO
+--------
+tg(1) git-send-email(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-PATCH(1)
+===========
+
+NAME
+----
+tg-patch - generate a patch from a TopGit branch
+
+SYNOPSIS
+--------
+*tg patch* ['-i' | '-w'] ['NAME']
+
+DESCRIPTION
+-----------
+The tg-patch command is part of the topgit's tools suite.
+
+It generates a patch from the current or specified topic branch.
+This means that the diff between the topic branch base and head (latest commit)
+is shown, appended to the description found in the .topmsg file.
+
+The patch is dumped to stdout.
+
+OPTIONS
+-------
+*-i*::
+Base patch generation on index instead of branch.
+
+*-w*::
+Base patch generation on working tree instead of branch.
+
+TODOS
+-----
+Send patches by emails or save them to files.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-REMOTE(1)
+===========
+
+NAME
+----
+tg-remote - register a remote branch as a TopGit topic branch
+
+SYNOPSIS
+--------
+*tg remote* ['--populate'] 'REMOTE'
+
+DESCRIPTION
+-----------
+The tg-remote command is part of the topgit's tool suite.
+
+It registers given remote as TopGit-controlled. This will create the namespace
+for the remote branch bases and teach *git fetch* and *git push* to operate on
+them. (Do NOT use 'git push --all' for your pushes - plain 'git push' will do
+the right thing.)
+
+OPTIONS
+-------
+*--populate*::
+Seed the local topic branch system based on the remote topic branches. It will
+also make *tg remote* automatically fetch the remote and *tg update* to look at
+branches of this remote for updates by default.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-SUMMARY(1)
+=============
+
+NAME
+----
+tg-summary - display an overview of all TopGit branches
+
+SYNOPSIS
+--------
+*tg summary* ['-t' | '--graphviz']
+
+DESCRIPTION
+-----------
+The tg-summary command is part of the topgit's tools suite.
+
+It shows an overview of all TopGit-tracked topic branches and their
+up-to-date status:
+
+'>' marks the current topic branch,
+
+'0' marks that it introduces no own changes,
+
+'l'/'r' marks that it is local-only or has remote mate,
+
+'L'/'R' marks that it is ahead/out-of-date wrt. its remote mate,
+
+'D' marks that it is out-of-date wrt. its dependencies,
+
+'!' marks that it has missing dependencies (even recursively),
+
+'B' marks that it is out-of-date wrt. its base).
+
+OPTIONS
+-------
+*-t*::
+This can take long time to accurately determine all the relevant information
+about each branch. Use this option to get a terse list of topic branch names
+quickly.
+*--graphviz*::
+Print a dot-suitable output on STDOUT to draw a dependency graph between the
+topic branches.
+
+TODOS
+-----
+Speed up by an order of magnitude.
+
+Text graph view.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-UPDATE(1)
+===========
+
+NAME
+----
+tg-update - update a TopGit branch
+
+SYNOPSIS
+--------
+*tg update*
+
+DESCRIPTION
+-----------
+The tg-update command is part of the topgit's tools suite.
+
+It updates the current topic branch wrt. changes in the branches it depends on
+and remote branches. This is performed in two phases - first, changes within
+the dependencies are merged to the base, then the base is merged into the topic
+branch. The output will guide you in case of conflicts.
+
+In case your dependencies are not up-to-date, tg update will first recurse into
+them and update these.
+
+If a remote branch update brings dependencies on branches not yet instantiated
+locally, you can either bring in all the new branches from the remote using
+*tg remote --populate* or only pick out the missing ones using *tg create -r*
+('tg summary' will point out branches with incomplete dependencies by showing
+an '!' near to them).
+
+TODOS
+-----
+tg update -a for updating all topic branches
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
+
+TG-EXPORT(1)
+===========
+
+NAME
+----
+tg-export - export history of a TopGit topic branch
+
+SYNOPSIS
+--------
+*tg export* (['--collapse'] 'NEWBRANCH' | '--quilt DIRECTORY' ['OPTIONS'] | '--linearize NEWBRANCH')
+
+DESCRIPTION
+-----------
+The tg-export command is part of the topgit's tool suite.
+
+It exports a tidied-up history of the current topic branch and its
+dependencies, suitable for feeding upstream. Each topic branch
+corresponds to a single commit or patch in the cleaned up history
+(corresponding basically exactly to *tg patch* output for the topic branch).
+
+The command has three possible outputs now - either a Git branch with
+the collapsed history, a Git branch with a linearized history, or a
+quilt series in new directory.
+
+In case of producing collapsed history in new branch, you can use this
+collapsed structure either for providing a pull source for upstream, or further
+linearization e.g. for creation of a quilt series using git log:
+
+ git log --pretty=email -p --topo-order origin..exported
+
+To better understand the function of *tg export*, consider this dependency
+structure of topic branches:
+
+ origin/master - t/foo/blue - t/foo/red - master
+ `- t/bar/good <,----------'
+ `- t/baz ------------'
+
+(Where each of the branches may have hefty history.) Then
+
+master$ tg export for-linus
+
+will create this commit structure on branch for-linus:
+
+ origin/master - t/foo/blue -. merge - t/foo/red -.. merge - master
+ `- t/bar/good <,-------------------'/
+ `- t/baz ---------------------'
+
+In case of using the linearize mode:
+
+ master$ tg export --linearize for-linus
+
+you get a linear history respecting the dependencies of your patches in a new
+branch for-linus. The result should be more or less the same as using quilt
+mode and reimporting it into a Git branch. (More or less because the topologic
+order can usually be extended in more than one way into a complete ordering and
+the two methods may choose different one's.) The result might be more
+appropriate for merging upstream as it contains fewer merges.
+
+Note that you might get conflicts during linearization because the patches are
+reordered to get a linear history.
+
+In case of the quilt mode,
+
+master$ tg export --quilt for-linus
+
+would create this directory for-linus:
+
+ for-linus/t/foo/blue.diff
+ for-linus/t/foo/red.diff
+ for-linus/t/bar/good.diff
+ for-linus/t/baz.diff
+ for-linus/series:
+ t/foo/blue.diff -p1
+ t/bar/good.diff -p1
+ t/foo/red.diff -p1
+ t/baz.diff -p1
+
+The command works on the current topic branch and can be called either without
+a parameter (in that case, '--collapse' is assumed) and with one mandatory
+argument: the name of the branch where the exported result shall be stored.
+The branch will be silently overwritten if it exists already! Use git reflog to
+recover in case of mistake.
+
+Alternatively, call it with the '--quilt' parameter and an argument specifying
+the directory where the quilt series should be saved.
+
+OPTIONS
+-------
+*-b BRANCH1,BRANCH2...*::
+In *quilt mode*, it specifies a list of branches to export.
+
+*--collapse*::
+Select the collapse mode (default mode).
+
+*--flatten*::
+In quilt mode, it subsitutes slashes by underscores in the patch names such
+they end up directly in the output directory.
+
+*--linearize NEWBRANCH*::
+Description
+
+*--numbered*::
+In quilt mode, the patch names get a number as prefix to allow getting the
+order without consulting the series file, which eases sending out the patches.
+this option implies *--flatten*.
+
+*--quilt DIRECTORY*::
+Select the quilt mode, and instruct topgit to add patches to *DIRECTORY*.
+
+TODOS
+-----
+Make stripping of non-essential headers configurable.
+
+Make stripping of [PATCH] and other prefixes configurable.
+
+--mbox option for other mode of operation.
+
+-a option to export all branches.
+
+For quilt exporting, export the linearized history created in a temporary
+branch --- this would allow producing conflict-less series.
+
+SEE-ALSO
+--------
+tg(1)
+
+AUTHORS
+-------
+Petr Baudis <pa...@ucw.cz>
+
+RESSOURCES
+----------
+Main web site: <http://repo.or.cz/w/topgit.git>
diff --git a/create-help.sh b/create-help.sh
index fbd9a09..9b37d61 100755
--- a/create-help.sh
+++ b/create-help.sh
@@ -7,12 +7,12 @@ if [ $# -ne 1 ] ; then
exit 1
fi
+TG_CMD=`echo $1 | tr '[:lower:]' '[:upper:]'`
+
< README awk '
- BEGIN { incommand = 0; }
- /^tg '"$1"'$/ { incommand = 1; next; }
- /^~/ { next; } # Ignore the title underlines.
- /^[^\t]/ { incommand = 0; next; }
+ /^TG/ { if (incommand) { incommand = 0; } }
+ /^'"$TG_CMD"'\(1\)$/ { incommand = 1; }
{ if (incommand) { print $0; } }
-' > tg-"$1".txt
+' > "$1".txt
# vim:noet
--
tg: (ee0520c..) t/upstream/manpages (depends on: t/debian/manpages)
signature.asc
Description: OpenPGP digital signature
