X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=1893dc0973093da0da231c76b4bfde734fabcc8c;hb=97ce88672c1c2bd6decabc54f5ae1e08e4ea8f32;hp=cc200cae41b7695b91e1cc768bf905c2b9ef764f;hpb=8c74e001a0cfdc7d0644c08834ec844a40fc45df;p=topgit.git diff --git a/README b/README index cc200ca..1893dc0 100644 --- 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, @@ -266,7 +321,10 @@ tg remote tg summary ~~~~~~~~~~ Show overview of all TopGit-tracked topic branches and their - up-to-date status ('0' marks that it introduces no own changes, + up-to-date status ('>' marks the current topic branch, + '0' marks that it introduces no own changes, + 'l'/'r' marks that it is local-only or has remote mate, + 'L'/'R' marks that it is ahead/out-of-date wrt. its remote mate, '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). @@ -337,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 @@ -344,11 +406,19 @@ 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/ by default; use '-p PREFIX' to specify + an alternative prefix (even an empty one). + tg update ~~~~~~~~~ Update the current topic branch wrt. changes in the branches @@ -361,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 @@ -457,3 +532,8 @@ carried over to our local base automagically. Then, the base is merged into remote branch and the result is merged to local branch - again, to carry over remote conflict resolutions. In the future, this order might be adjustable per-update in case local changes are diverging more than the remote ones. + +All commands by default refer to the remote that 'tg remote --populate' +was called on the last time ('topgit.remote' configuration variable). You can +manually run any command with a different base remote by passing '-r REMOTE' +_before_ the subcommand name.