X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=275043b2c2bd05060dd011a369e9739cce1cad07;hb=074eb3f1b432d95880fcc2c5b388bebac75046e9;hp=dc2e5ff320bbf788e2d5aed02602a0753990584b;hpb=ab712f2ed92a6e451bf2d482b03d2559697bf100;p=topgit.git

diff --git a/README b/README
index dc2e5ff..275043b 100644
--- a/README
+++ b/README
@@ -203,7 +203,10 @@ tg create
 	the current branch is assumed to be the only dependency.
 
 	After `tg create`, you should insert the patch description
-	to the '.topmsg' file.
+	to the '.topmsg' file, which will already contain some
+	pre-filled 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.
@@ -242,7 +245,7 @@ tg patch
 
 	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.
+	or save them to files. (TODO)
 
 	TODO: tg patch -i to base at index instead of branch,
 		-w for working tree
@@ -258,6 +261,50 @@ tg summary
 	TODO: Speed up by an order of magnitude
 	TODO: Graph view
 
+tg export
+~~~~~~~~~
+	Create a new branch containing tidied-up history
+	of the current topic branch and its dependencies,
+	suitable for pull by upstream - each topic branch
+	corresponds to a single commit in the cleaned up history
+	(corresponding basically exactly to `tg patch` output
+	for the topic 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      ---------------------'
+
+	The command works on the current topic branch
+	and requires 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.
+
+	Usage: tg export BRANCH
+
+	TODO: Make stripping of non-essential headers configurable
+	TODO: Make stripping of [PATCH] and other prefixes configurable
+	TODO: --quilt and --mbox options for other modes of operation
+
 tg update
 ~~~~~~~~~
 	Update the current topic branch wrt. changes in the branches
@@ -306,6 +353,8 @@ mail headers are inserted and the patch itself is appended.
 Thus, as your patches evolve, you can record nuances like whether
 the paricular patch should have To-list/Cc-maintainer or vice
 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
 your patch depends on, pre-seeded with `tg create`. (Continuously