Merge commit 'refs/top-bases/fixes/tg--r-require-arg' into fixes/tg--r-require-arg

[topgit.git] / README

diff --git a/README b/README
index 8be0d17ec0e005ce08693505097e4fa9e38d9131..c418ff41a694b3920af6854d01f8b64f1ecc94d4 100644 (file)
--- 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
@@ -284,8 +288,9 @@ tg patch
        tg patch will be able to automatically send the patches by mail
        or save them to files. (TODO)
 
-       TODO: tg patch -i to base at index instead of branch,
-               -w for working tree
+       Options:
+         -i            base patch generation on index instead of branch
+         -w            base patch generation on working tree instead of branch
 
 tg mail
 ~~~~~~~
@@ -303,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
@@ -350,11 +362,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:
 
@@ -377,6 +390,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
@@ -409,14 +437,23 @@ tg export
        a comma-separated explicit list of branches to export. This
        mode of operation is currently not supported with collapse.
 
-       Usage: tg export ([--collapse] BRANCH | --quilt DIR)
+       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, 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
 ~~~~~~~~~
@@ -454,6 +491,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