Merge commit 'refs/top-bases/debian/locations' into debian/locations

[topgit.git] / README

diff --git a/README b/README
index f380475436a6bd1f116fd193aa1aafbac8aa3f0a..1893dc0973093da0da231c76b4bfde734fabcc8c 100644 (file)
--- a/README
+++ b/README
@@ -184,6 +184,24 @@ SYNOPSIS
        tg: Updating base with t/gitweb/nifty-links changes...
        tg: Updating t/whatever against new base...
 
+       ## Clone a TopGit-controlled repository
+       $ git clone URL repo
+       $ cd repo
+       $ tg remote --populate origin
+       ...
+       $ git fetch
+       $ tg update
+
+       ## Add a TopGit remote to a repository and push to it
+       $ git remote add foo URL
+       $ tg remote foo
+       $ git push foo
+
+       ## Update from a non-default TopGit remote
+       $ git fetch foo
+       $ tg -r foo summary
+       $ tg -r foo update
+
 
 USAGE
 -----
@@ -215,6 +233,10 @@ tg create
        it will detect that you are on a topic branch base ref and
        resume the topic branch creation operation.
 
+       In an alternative use case, if '-r BRANCH' is given instead
+       of dependency list, the topic branch is created based on
+       the given remote branch.
+
 tg delete
 ~~~~~~~~~
        Remove a TopGit-controlled topic branch of given name
@@ -231,6 +253,19 @@ tg delete
 
        TODO: '-a' to delete all empty branches, depfix, revert
 
+tg depend
+~~~~~~~~~
+       Change dependencies of a TopGit-controlled topic branch.
+       This should have several subcommands, but only 'add' is
+       supported right now.
+
+       The 'add' subcommand takes an argument of a topic branch
+       to be added, adds it to '.topdeps', performs a commit and
+       then updates your topic branch accordingly. If you want to
+       do other things related to the dependency addition, like
+       adjusting '.topmsg', prepare them in the index before
+       calling 'tg depend add'.
+
 tg info
 ~~~~~~~
        Show a summary information about the current or specified
@@ -250,11 +285,31 @@ tg patch
        TODO: tg patch -i to base at index instead of branch,
                -w for working tree
 
+tg mail
+~~~~~~~
+       Send a patch from the current or specified topic branch as
+       email.
+
+       Takes the patch given on the command line and emails it out.
+       Destination addresses such as To, Cc and Bcc are taken from the
+       patch header.
+
+       Since it actually boils down to `git send-email` please refer to
+       its documentation for details on how to setup email for git.
+       You can pass arbitrary options to this command through the
+       '-s' parameter, but you must double-quote everything.
+
+       TODO: 'tg mail patchfile' to mail an already exported patch
+       TODO: mailing patch series
+       TODO: specifying additional options and addresses on command
+             line
+
 tg remote
 ~~~~~~~~~
        Register given remote as TopGit-controlled. This will create
        the namespace for the remote branch bases and teach 'git fetch'
-       and 'git push' to operate on them.
+       and 'git push' to operate on them. (Do NOT use 'git push --all'
+       for your pushes - plain 'git push' will do the right thing.)
 
        It takes a mandatory remote name argument, and optional
        '--populate' switch - use that for your origin-style remote,
@@ -340,6 +395,10 @@ tg export
        and an argument specifying the directory
        where the quilt series should be saved.
 
+       With '--quilt', you can also pass '-b' parameter followed by
+       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)
 
        TODO: Make stripping of non-essential headers configurable
@@ -347,19 +406,18 @@ tg export
        TODO: --mbox option for other mode of operation
        TODO: -n option to prevent exporting of empty patches
        TODO: -a option to export all branches
-       TODO: Allow branches to be exported to be passed as arguments, default
-             to the current branch if none are specified
        TODO: For quilt exporting, use a temporary branch and remove it when
              done - this would allow producing conflict-less series
 
 tg import
-~~~~~~~~
+~~~~~~~~~
        Import commits within the given revision range into TopGit,
        creating one topic branch per commit, the dependencies forming
        a linear sequence starting on your current branch.
 
        The branch names are auto-guessed from the commit messages
-       and prefixed by t/.
+       and prefixed by t/ by default; use '-p PREFIX' to specify
+       an alternative prefix (even an empty one).
 
 tg update
 ~~~~~~~~~
@@ -373,10 +431,15 @@ tg update
        In case your dependencies are not up-to-date, tg update
        will first recurse into them and update these.
 
+       If a remote branch update brings dependencies on branches
+       not yet instantiated locally, you can either bring in all
+       the new branches from the remote using 'tg remote --populate'
+       or only pick out the missing ones using 'tg create -r'
+       ('tg summary' will point out branches with incomplete
+       dependencies by showing an '!' near to them).
+
        TODO: tg update -a for updating all topic branches
 
-TODO: Some infrastructure for sharing topic branches between
-       repositories easily
 TODO: tg depend for adding/removing dependencies smoothly
 TODO: tg rename