X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=README;h=b58a1b43e8f7383ed53b60464886d6efaf08de1a;hb=e5274deedc606f3a2eb69886e127a60534a82872;hp=be7be1bc0b865aae5e705875bf7699f9b02a0d5c;hpb=f59eab26c07ba70181c4677a1aab4bc42502271e;p=topgit.git diff --git a/README b/README index be7be1b..b58a1b4 100644 --- a/README +++ b/README @@ -86,9 +86,9 @@ SYNOPSIS $ ..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 - $ 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 @@ -100,7 +100,7 @@ SYNOPSIS 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! @@ -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 - 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 - 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. @@ -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. - '-d': - Manually specified dependencies. A comma- or - space-separated list of branch names. - 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 - 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 @@ -262,6 +261,75 @@ tg summary 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 @@ -278,8 +346,6 @@ tg update TODO: Some infrastructure for sharing topic branches between repositories easily TODO: tg depend for adding/removing dependencies smoothly -TODO: tg collapse for creating a one-commit-per-patch tidied up - history (for pulling by upstream) IMPLEMENTATION @@ -310,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. +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