X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=d7dfb5f6497ca03776f7c883b493e4a365332922;hb=cbcc4775db9a1b8bd1cb0cb0a9181227b50af279;hp=5796112db59a7d09f7897caa600b6f3233054f20;hpb=d400bb3263ab1239cc219541bb4364135b1b753e;p=topgit.git

diff --git a/README b/README
index 5796112..d7dfb5f 100644
--- a/README
+++ b/README
@@ -244,6 +244,10 @@ tg delete
 	only empty branch (base == head); use '-f' to remove
 	non-empty branch.
 
+	The '-f' option is also useful to force removal of a branch's base, if
+	you used 'git branch -D B' to remove the branch B, and then certain
+	TopGit commands complain, because the base of branch B is still there.
+
 	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
@@ -304,6 +308,13 @@ tg mail
 	The '-r' parameter with msgid can be used to generate in-reply-to
 	and reference headers to an earlier mail.
 
+	Note: be careful when using this command.  It easily sends out several
+	mails.  You might want to run
+
+		git config sendemail.confirm always
+
+	to let `git send-email` ask for confirmation before sending any mail.
+
 	TODO: 'tg mail patchfile' to mail an already exported patch
 	TODO: mailing patch series
 	TODO: specifying additional options and addresses on command
@@ -340,6 +351,17 @@ tg summary
 	pass '--graphviz' to get a dot-suitable output to draw a dependency
 	graph between the topic branches.
 
+	You can also use the --sort option to sort the branches using
+	a topological sort.  This is especially useful if each
+	TopGit-tracked topic branch depends on a single parent branch,
+	since it will then print the branches in the dependency
+	order.  In more complex scenarios, a text graph view would be
+	much more useful, but that is not yet implemented.
+
+	The --deps option outputs dependency informations between
+	branches in a machine-readable format.  Feed this to "tsort"
+	to get the output from --sort.
+
 	TODO: Speed up by an order of magnitude
 	TODO: Text graph view
 
@@ -351,11 +373,12 @@ tg export
 	in the cleaned up history (corresponding basically exactly
 	to `tg patch` output for the topic branch).
 
-	The command has two possible outputs now - either a Git branch
-	with the collapsed history, or a quilt series in new directory.
+	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
+	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:
 
@@ -378,6 +401,21 @@ tg export
 	             `- 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
@@ -418,14 +456,15 @@ tg export
 	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] BRANCH | --quilt DIR)
+	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, use a temporary branch and remove it when
-	      done - this would allow producing conflict-less series
+	TODO: For quilt exporting, export the linearized history created in a
+	      temporary branch---this would allow producing conflict-less
+	      series
 
 tg import
 ~~~~~~~~~
@@ -463,6 +502,12 @@ tg update
 
 	TODO: tg update -a for updating all topic branches
 
+tg push
+~~~~~~~
+	pushes a TopGit-controlled topic branch to a remote
+	repository.  By default the remote gets all dependencies
+	(both tgish and non-tgish) and bases pushed to.
+
 TODO: tg rename