tg-export: New command for cleaning up history

[topgit.git] / README

diff --git a/README b/README
index dc2e5ff320bbf788e2d5aed02602a0753990584b..275043b2c2bd05060dd011a369e9739cce1cad07 100644 (file)
--- 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
        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.
 
        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
 
        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
 
        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
 
        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
 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.
 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
 
        .topdeps: Contains the one-per-line list of branches
 your patch depends on, pre-seeded with `tg create`. (Continuously