        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 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 the case where you are producing collapsed history in a new
        branch, you can use this collapsed structure either for
        providing a pull source for upstream, or for 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:

         origin/master - t/foo/blue - t/foo/red - master
                      `- t/bar/good <,----------'
                      `- t/baz      ------------'

        (where each of the branches may have a hefty history). Then:

         master$ tg export for-linus

        will create this commit structure on the branch `for-linus`:

         origin/master - t/foo/blue -. merge - t/foo/red -.. merge - master
                      `- t/bar/good <,-------------------'/
                      `- t/baz      ---------------------'

        In this mode, `tg export` works on the current topic branch, and
        can be called either without an option (in that case,
        `--collapse` is assumed), or with the `--collapse` option, and
        with one mandatory argument: the name of the branch where the
        exported result will be stored.

        Both the `--collapse` and `--linearize` modes also accept a
        `-s <mode>` option to specify subject handling behavior for the
        freshly created commits.  There are five possible modes:

                "keep"         Like `git mailinfo -k`
                "mailinfo"     Like `git mailinfo`
                "patch"        Remove first [PATCH*] if any
                "topgit"       Remove first [PATCH*], [BASE], [ROOT] or [STAGE]
                "trim"         Trim runs of spaces/tabs to a single space

        The `topgit` (aka `tg`) mode is the default (quelle surprise) and
        like the `patch` mode will only strip the first square brackets tag
        (if there is one) provided it's a TopGit-known tag (the `patch`
        variation will only strip a "[PATCH*]" tag but still just the first
        one).  Note that TopGit does understand "[RELEASE]" in `topgit` mode.
        With `trim` (aka `ws`) internal runs of spaces/tabs are converted
        to a single space, but no square brackets tags are removed.  The `ws`
        mode should generally be preferred instead of using `keep` mode.
        All modes always remove leading/trailing spaces and tabs and if the
        `topgit.subjectPrefix` value (see "tg create") has been set both the
        `topgit` and `patch` modes will match tags with that prefix too.

        Setting the config variable `topgit.subjectMode` to one of the mode
        values shown above will change the default to that mode.

        Both the `--collapse` and `--linearize` modes also accept a
        `--notes[=<ref>]` option to export the portion of the .topmsg file
        following a `---` separator line to the specified notes ref.  If
        `<ref>` is omitted then `refs/notes/commits` will be used.  If
        `<ref>` does not start with `refs/notes/` then `refs/notes/`
        will be prepended unless it starts with `notes/` in which case
        only `refs/` will be prepended.

        Setting the config variable `topgit.notesExport` to a boolean or
        to a `<ref>` name will set the default for the `--notes` option
        (with no config or `--notes[=<ref>]` option the `---` comment is
        discarded by default).  To override a `topgit.notesExport` option
        and discard any `---` comments, use `--no-notes`.

        When 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 then reimporting it
        into a Git branch.  (More or less because the topological order
        can usually be extended in more than one way into a total order,
        and the two methods may choose different ones.)  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.  If linearization
        would produce conflicts then using `--quilt` will also likely result
        in conflicts when the exported quilt series is applied.  Since the
        `--quilt` mode simply runs a series of `tg patch` commands to
        generate the patches in the exported quilt series and those patches
        will end up being applied linearly, the same conflicts that would be
        produced by the `--linearize` option will then occur at that time.

        To avoid conflicts produced by `--linearize` (or by applying the
        `--quilt` output), use the default `--collapse` mode and then use
        `tg rebase` (or `git rebase -m` directly) on the collapsed branch
        (with a suitable <upstream>) followed by `git format-patch` on the
        rebased result to produce a conflict-free patch set.  A suitable
        upstream may be determined with the `tg info --leaves` command (if
        it outputs more than one line, linearization will be problematic).

        You have enabled `git rerere` haven't you?

        When using the quilt mode:

         master$ tg export --quilt for-linus

        would create the following 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

        With `--quilt`, you can also pass the `-b` parameter followed
        by a comma-separated explicit list of branches to export, or
        the `--all` parameter (which can be shortened to `-a`) to
        export them all.  The `--binary` option enables producing Git
        binary patches.  These options are currently only supported
        with `--quilt`.

        In `--quilt` mode the patches are named like the originating
        topgit branch.  So usually they end up in subdirectories of the
        output directory.  With the `--flatten` option the names are
        mangled so that they end up directly in the output dir (slashes
        are replaced with underscores).  With the `--strip[=N]` option
        the first `N` subdirectories (all if no `N` is given) get
        stripped off.  Names are always `--strip`'d before being
        `--flatten`'d.  With the option `--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.

        Note that `tg export` is fully compatible with the "WAYBACK MACHINE"
        and when used with the `--collapse` or `--linearize` options will
        "push" the resulting branch back into the main repository when used in
        wayback mode.

        | TODO: Make stripping of non-essential headers configurable
        | TODO: `--mbox` option to export instead as an mbox file
        | TODO: support `--all` option in other modes of operation
        | TODO: For quilt exporting, export the linearized history created in
                a temporary branch--this would allow producing conflict-less
                series

