Force adding the .topmsg and .topdep files.

[topgit.git] / README

diff --git a/README b/README
index 82d185f7681ea02c6cf47a6a8cf10777c211e109..b58a1b43e8f7383ed53b60464886d6efaf08de1a 100644 (file)
--- a/README
+++ b/README
@@ -86,9 +86,9 @@ SYNOPSIS
        $ ..hack..
        $ git commit
 
        $ ..hack..
        $ git commit
 

-       ## Create another topic branch on top of specified one and submit
+       ## Create another topic branch on top of master and submit

        ## the resulting patch upstream
        ## the resulting patch upstream

-       $ tg create -d master t/revlist/author-fixed
+       $ tg create t/revlist/author-fixed master

        tg: Creating t/revlist/author-fixed base from master...
        $ ..hack..
        $ git commit
        tg: Creating t/revlist/author-fixed base from master...
        $ ..hack..
        $ git commit


@@ -100,7 +100,7 @@ SYNOPSIS
        Subject: [PATCH] Fix broken revlist --author when --fixed-string
 
        ## Create another topic branch depending on two others non-trivially
        Subject: [PATCH] Fix broken revlist --author when --fixed-string
 
        ## Create another topic branch depending on two others non-trivially

-       $ tg create -d t/revlist/author-fixed,t/gitweb/nifty-links t/whatever
+       $ tg create t/whatever t/revlist/author-fixed t/gitweb/nifty-links

        tg: Creating t/whatever base from t/revlist/author-fixed...
        tg: Merging t/whatever base with t/gitweb/nifty-links...
        Merge failed!
        tg: Creating t/whatever base from t/revlist/author-fixed...
        tg: Merging t/whatever base with t/gitweb/nifty-links...
        Merge failed!


@@ -199,11 +199,14 @@ tg create
 ~~~~~~~~~
        Create a new TopGit-controlled topic branch of a given name
        (required argument) and switch to it. If no dependencies
 ~~~~~~~~~
        Create a new TopGit-controlled topic branch of a given name
        (required argument) and switch to it. If no dependencies

-       are specified using the '-d' paremeter, the current branch
-       is assumed to be the only dependency.
+       are specified (by extra arguments passed after the first one),
+       the current branch is assumed to be the only dependency.

 
        After `tg create`, you should insert the patch description
 
        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.


@@ -212,10 +215,6 @@ tg create
        it will detect that you are on a topic branch base ref and
        resume the topic branch creation operation.
 
        it will detect that you are on a topic branch base ref and
        resume the topic branch creation operation.
 

-       '-d':
-               Manually specified dependencies. A comma- or
-               space-separated list of branch names.
-

 tg delete
 ~~~~~~~~~
        Remove a TopGit-controlled topic branch of given name
 tg delete
 ~~~~~~~~~
        Remove a TopGit-controlled topic branch of given name


@@ -246,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


@@ -256,11 +255,81 @@ tg summary
        Show overview of all TopGit-tracked topic branches and their
        up-to-date status ('0' marks that it introduces no own changes,
        'D' marks that it is out-of-date wrt. its dependencies,
        Show overview of all TopGit-tracked topic branches and their
        up-to-date status ('0' marks that it introduces no own changes,
        'D' marks that it is out-of-date wrt. its dependencies,

+       '!' marks that it has missing dependencies (even recursively),

        'B' marks that it is out-of-date wrt. its base).
 
        TODO: Speed up by an order of magnitude
        TODO: Graph view
 
        'B' marks that it is out-of-date wrt. its base).
 
        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
 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: Some infrastructure for sharing topic branches between
        repositories easily
 TODO: tg depend for adding/removing dependencies smoothly

-TODO: tg tidy for creating a one-commit-per-patch tidied up history
-       (for pulling by upstream)

 
 
 IMPLEMENTATION
 
 
 IMPLEMENTATION


@@ -309,6 +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.
 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