tg create: Set up refs/top-bases/ after conflict resolution

[topgit.git] / README

diff --git a/README b/README
index bd4f17a54d8b493e143469dd1e3d2a4eac9f07d1..b58a1b43e8f7383ed53b60464886d6efaf08de1a 100644 (file)
--- a/README
+++ b/README
@@ -261,6 +261,75 @@ tg summary
        TODO: Speed up by an order of magnitude
        TODO: 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 two posible outputs now - either a Git branch
+       with the collapsed 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 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.
+
+       Usage: tg export ([--collapse] 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
+
 tg update
 ~~~~~~~~~
        Update the current topic branch wrt. changes in the branches
@@ -277,8 +346,6 @@ tg update
 TODO: Some infrastructure for sharing topic branches between
        repositories easily
 TODO: tg depend for adding/removing dependencies smoothly
-TODO: tg collapse for creating a one-commit-per-patch tidied up
-       history (for pulling by upstream)
 
 
 IMPLEMENTATION
@@ -309,8 +376,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, the To,
-Cc and Bcc can be prefilled from optional topgit.{to,cc,bcc}.
+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