From: Robin Green Date: Sat, 9 Mar 2013 11:51:28 +0000 (+0000) Subject: Documentation cleanup X-Git-Tag: topgit-0.9~1 X-Git-Url: https://repo.or.cz/w/topgit.git/commitdiff_plain/6729dea205cd9559cfc1a0ea555bb8dc24d09ccc Documentation cleanup --- diff --git a/README b/README index b798acd..d3d82df 100644 --- a/README +++ b/README @@ -4,12 +4,12 @@ TopGit - A different patch queue manager DESCRIPTION ----------- -TopGit aims to make handling of large amount of interdependent topic -branches easier. In fact, it is designed especially for the case -when you maintain a queue of third-party patches on top of another -(perhaps Git-controlled) project and want to easily organize, maintain -and submit them - TopGit achieves that by keeping a separate topic -branch for each patch and providing few tools to maintain the branches. +TopGit aims to make handling of large amounts of interdependent topic +branches easier. In fact, it is designed especially for the case where +you maintain a queue of third-party patches on top of another (perhaps +Git-controlled) project and want to easily organize, maintain and submit +them - TopGit achieves that by keeping a separate topic branch for each +patch and providing some tools to maintain the branches. INSTALLATION @@ -20,47 +20,46 @@ See the file INSTALL. RATIONALE --------- -Why not use something like StGIT or Guilt or rebase -i for maintaining +Why not use something like StGIT or Guilt or 'rebase -i' for maintaining your patch queue? The advantage of these tools is their simplicity; they work with patch _series_ and defer to the reflog facility for version control of patches (reordering of patches is not -version-controlled at all). But there are several disadvantages - -for one, these tools (especially StGIT) do not actually fit well -with plain Git at all: it is basically impossible to take advantage -of the index effectively when using StGIT. But more importantly, -these tools horribly fail in the face of distributed environment. +version-controlled at all). But there are several disadvantages - for +one, these tools (especially StGIT) do not actually fit well with plain +Git at all: it is basically impossible to take advantage of the index +effectively when using StGIT. But more importantly, these tools +horribly fail in the face of a distributed environment. TopGit has been designed around three main tenets: - (i) TopGit is as thin layer on top of Git as possible. -You still maintain your index and commit using Git, TopGit will -only automate few indispensable tasks. + (i) TopGit is as thin a layer on top of Git as possible. You +still maintain your index and commit using Git; TopGit will only +automate a few indispensable tasks. - (ii) TopGit is anxious about _keeping_ your history. It will -never rewrite your history and all metadata is also tracked by Git, -smoothly and non-obnoxiously. It is good to have a _single_ point -when the history is cleaned up, and that is at the point of inclusion -in the upstream project; locally, you can see how your patch has evolved -and easily return to older versions. + (ii) TopGit is anxious about _keeping_ your history. It will +never rewrite your history, and all metadata is also tracked by Git, +smoothly and non-obnoxiously. It is good to have a _single_ point when +the history is cleaned up, and that is at the point of inclusion in the +upstream project; locally, you can see how your patch has evolved and +easily return to older versions. - (iii) TopGit is specifically designed to work in distributed -environment. You can have several instances of TopGit-aware repositories -and smoothly keep them all up-to-date and transfer your changes between -them. + (iii) TopGit is specifically designed to work in a distributed +environment. You can have several instances of TopGit-aware +repositories and smoothly keep them all up-to-date and transfer your +changes between them. As mentioned above, the main intended use-case for TopGit is tracking third-party patches, where each patch is effectively a single topic branch. In order to flexibly accommodate even complex scenarios when -you track many patches where many are independent but some depend -on others, TopGit ignores the ancient Quilt heritage of patch series -and instead allows the patches to freely form graphs (DAGs just like -Git history itself, only "one level higher"). For now, you have -to manually specify which patches does the current one depend -on, but TopGit might help you with that in the future in a darcs-like -fashion. +you track many patches where many are independent but some depend on +others, TopGit ignores the ancient Quilt heritage of patch series and +instead allows the patches to freely form graphs (DAGs just like Git +history itself, only "one level higher"). For now, you have to manually +specify which patches the current one depends on, but TopGit might help +you with that in the future in a darcs-like fashion. -A glossary plug: The union (i.e. merge) of patch dependencies is -called a _base_ of the patch (topic branch). +A glossary plug: The union (i.e. merge) of patch dependencies is called +a _base_ of the patch (topic branch). Of course, TopGit is perhaps not the right tool for you: @@ -200,8 +199,7 @@ SYNOPSIS ## Add a TopGit remote to a repository and push to it $ git remote add foo URL $ tg remote foo - $ tg push -r foo t/whatever - # Note that magit still uses git push, which is wrong as of TopGit 0.8 + $ tg push -r foo ## Update from a non-default TopGit remote $ git fetch foo @@ -212,69 +210,77 @@ SYNOPSIS USAGE ----- -The 'tg' tool of TopGit has several subcommands: +The 'tg' tool has several subcommands: tg help ~~~~~~~ - Our sophisticated integrated help facility. Doesn't do - a whole lot for now. + Our sophisticated integrated help facility. Mostly duplicates + what is below, except for adding summary Usage lines. + + # to list commands: + $ tg help + # to get help for a particular command: + $ tg help tg create ~~~~~~~~~ - Create a new TopGit-controlled topic branch of a given name - (required argument) and switch to it. If no dependencies - 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, which will already contain some - prefilled 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. - In that case, after you commit the conflicts resolution, - you should call `tg create` again (without any arguments); - 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. + Create a new TopGit-controlled topic branch of the given name + (required argument) and switch to it. If no dependencies 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 into + the '.topmsg' file, which will already contain some prefilled + bits. You can set the 'topgit.to', 'topgit.cc' and 'topgit.bcc' + git configuration variables (see `man git-config`) in order to + have `tg create` add these headers with the 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. + In that case, after you commit the conflict resolution, you + should call `tg create` again (without any arguments); 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 a + dependency list, the topic branch is created based on the given + remote branch. tg delete ~~~~~~~~~ - Remove a TopGit-controlled topic branch of given name - (required argument). Normally, this command will remove - only empty branch (base == head) without dependencies; use '-f' - to remove non-empty branch or branch that is dependent upon. - - The '-f' option is also useful to force removal of a branch's base, if - you used 'git branch -D B' to remove the branch B, and then certain - TopGit commands complain, because the base of branch B is still there. - - Currently, this command will _NOT_ remove the branch from - the dependency list in other branches. You need to take - care of this _manually_. This is even more complicated - in combination with '-f', in that case you need to manually - unmerge the removed branch's changes from the branches - depending on it. + Remove a TopGit-controlled topic branch of the given name + (required argument). Normally, this command will remove only an + empty branch (base == head) without dependendents; use '-f' to + remove a non-empty branch or a branch that is depended upon by + another branch. + + The '-f' option is also useful to force removal of a branch's + base, if you used `git branch -D B` to remove branch B, and then + certain TopGit commands complain, because the base of branch B + is still there. + + IMPORTANT: Currently, this command will _NOT_ remove the branch + from the dependency list in other branches. You need to take + care of this _manually_. This is even more complicated in + combination with '-f' - in that case, you need to manually + unmerge the removed branch's changes from the branches depending + on it. 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 + Change the 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'. + The `add` subcommand takes an argument naming 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`. TODO: Subcommand for removing dependencies, obviously @@ -288,19 +294,19 @@ tg files tg info ~~~~~~~ - Show a summary information about the current or specified - topic branch. + Show summary information about the current or specified topic + branch. tg patch ~~~~~~~~ Generate a patch from the current or specified topic branch. - This means that the diff between the topic branch base and - head (latest commit) is shown, appended to the description - found in the .topmsg file. + This means that the diff between the topic branch base and head + (latest commit) is shown, appended to the description found in + the '.topmsg' file. - 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. (TODO) + The patch is simply dumped to stdout. In the future, `tg patch` + will be able to automatically send the patches by mail or save + them to files. (TODO) Options: -i base patch generation on index instead of branch @@ -309,25 +315,26 @@ tg patch tg mail ~~~~~~~ Send a patch from the current or specified topic branch as - email. + email(s). 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. - The '-r' parameter with msgid can be used to generate in-reply-to + Since it actually boils down to `git send-email`, please refer + to the documentation for that 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. The + '-r' parameter with a msgid can be used to generate in-reply-to and reference headers to an earlier mail. - Note: be careful when using this command. It easily sends out several - mails. You might want to run + WARNING: be careful when using this command. It easily sends + out several mails. You might want to run git config sendemail.confirm always - to let `git send-email` ask for confirmation before sending any mail. + to let `git send-email` ask for confirmation before sending any + mail. Options: -i base patch generation on index instead of branch @@ -340,110 +347,120 @@ tg mail tg remote ~~~~~~~~~ - Register given remote as TopGit-controlled. This will create - the namespace for the remote branch bases and teach 'git fetch' + Register the given remote as TopGit-controlled. This will create + the namespace for the remote branch bases and teach `git fetch` to operate on them. However, from TopGit 0.8 onwards you need to - use 'tg push', or 'git push --mirror', for pushing TopGit-controlled - branches. + use `tg push`, or `git push --mirror`, for pushing + TopGit-controlled branches. - 'tg remote' takes a optional remote name argument, and optional - '--populate' switch - use that for your origin-style remote, - it will seed the local topic branch system based on the - remote topic branches. '--populate' will also make 'tg remote' - automatically fetch the remote and 'tg update' to look at - branches of this remote for updates by default. + `tg remote` takes an optional remote name argument, and an + optional '--populate' switch. Use '--populate' for your + origin-style remotes: it will seed the local topic branch system + based on the remote topic branches. '--populate' will also make + `tg remote` automatically fetch the remote, and `tg update` look + at branches of this remote for updates by default. tg summary ~~~~~~~~~~ Show overview of all TopGit-tracked topic branches and their 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). - - This can take long time to accurately determine all the relevant - information about each branch; you can pass '-t' to get just - terse list of topic branch names quickly. Alternately, you can - pass '--graphviz' to get a dot-suitable output to draw a dependency - graph between the topic branches. - - You can also use the --sort option to sort the branches using + '0' indicates that it introduces no changes of its own, + 'l'/'r' indicates respectively whether it is local-only or has a remote mate, + 'L'/'R' indicates respectively if it is ahead or out-of-date with respect to its remote mate, + 'D' indicates that it is out-of-date with respect to its dependencies, + '!' indicates that it has missing dependencies [even if they are recursive ones], and + 'B' indicates that it is out-of-date with respect to its base). + + This can take a long time to accurately determine all the + relevant information about each branch; you can pass '-t' to get + just a terse list of topic branch names quickly. Alternately, + you can pass '--graphviz' to get a dot-suitable output to draw a + dependency graph between the topic branches. + + You can also use the '--sort' option to sort the branches using a topological sort. This is especially useful if each TopGit-tracked topic branch depends on a single parent branch, - since it will then print the branches in the dependency - order. In more complex scenarios, a text graph view would be - much more useful, but that is not yet implemented. + since it will then print the branches in the dependency order. + In more complex scenarios, a text graph view would be much more + useful, but that has not yet been implemented. - The --deps option outputs dependency informations between - branches in a machine-readable format. Feed this to "tsort" - to get the output from --sort. + The --deps option outputs dependency information between + branches in a machine-readable format. Feed this to `tsort` to + get the output from --sort. Options: - -i Use TopGit meta data from the index instead of branch - -w Use TopGit meta data from the working tree instead of branch + -i Use TopGit metadata from the index instead of the branch + -w Use TopGit metadata from the working tree instead of the branch TODO: Speed up by an order of magnitude TODO: Text 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). + 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. + 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 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: + 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 of topic branches: + 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 hefty history.) Then + (where each of the branches may have a hefty history). Then master$ tg export for-linus - will create this commit structure on branch 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 case of using the linearize mode: + 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. + + WARNING: The branch will be silently overwritten if it exists + already! If you make a mistake, use `git reflog` to recover. + + 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 reimporting it into a Git branch. (More or less - because the topologic order can usually be extended in more than one - way into a complete ordering and the two methods may choose different - one's.) The result might be more appropriate for merging upstream as - it contains fewer merges. + 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. + Note that you might get conflicts during linearization because + the patches are reordered to get a linear history. - In case of the quilt mode, + When using the quilt mode, master$ tg export --quilt for-linus - would create this directory for-linus: + would create the following directory 'for-linus': for-linus/t/foo/blue.diff for-linus/t/foo/red.diff @@ -455,33 +472,21 @@ tg export 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. - 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. - - In '--quilt' mode the patches are named like the originating topgit - branch. So usually they end up in subdirectories of the output - directory. With option '--flatten' the names are mangled such that - they end up directly in the output dir (i.e. slashes are substituted by - underscores). With option '--strip[=N]' the first 'N' subdirectories (all - if no 'N' is given) get stripped off. Names are always '--strip'ped - before '--flatten'ed. With 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. - - Usage: tg export ([(--collapse | --linearize)] BRANCH | --quilt DIR) + mode of operation is currently not supported with '--collapse'. + + 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 substituted by underscores). With the '--strip[=N]' option + the first 'N' subdirectories (all if no 'N' is given) get + stripped off. Names are always '--strip'ped before being + '--flatten'ed. 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. TODO: Make stripping of non-essential headers configurable TODO: Make stripping of [PATCH] and other prefixes configurable @@ -494,52 +499,53 @@ tg export 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 (or a branch - specified by the '-d' parameter). + creating one topic branch per commit. The dependencies are set + up to form a linear sequence starting on your current branch - + or a branch specified by the '-d' parameter, if present. - 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). + The branch names are auto-guessed from the commit messages and + prefixed by 't/' by default; use '-p ' to specify an + alternative prefix (even an empty one). Alternatively, you can use the '-s NAME' parameter to specify - the name of target branch; the command will then take one more - argument describing a single commit to import. + the name of the target branch; the command will then take one + more argument describing a _single_ commit to import. tg update ~~~~~~~~~ - Update the current, specified or all topic branches wrt. changes - in the branches they depends on and remote branches. - This is performed in two phases - first, - changes within the dependencies are merged to the base, - then the base is merged into the topic branch. - The output will guide you in case of conflicts. - - When -a is specifed, updates all topic branches matched by - PATTERNs (see git-for-all-refs(1) for details) or all if - no pattern is given. - - After the update if single topic branch was specified, it is left - as current; if -a was specified, returns to branch which was - current at the beginning. - - 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). + Update the current, specified or all topic branches with respect + to changes in the branches they depend on and remote branches. + This is performed in two phases - first, changes within the + dependencies are merged to the base, then the base is merged + into the topic branch. The output will guide you on what to do + next in case of conflicts. + + When '-a' is specifed, updates all topic branches matched by + s (see `git-for-all-refs(1)` for details), or all if + no is given. + + After the update, if a single topic branch was specified, it is + left as the current one; if '-a' was specified, it returns to + the branch which was current at the beginning. + + If your dependencies are not up-to-date, `tg update` will first + recurse into them and update them. + + If a remote branch update brings in dependencies on branches + that are 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 '!' next to them). TODO: tg update -a -c to autoremove (clean) up-to-date branches tg push ~~~~~~~ - pushes a TopGit-controlled topic branch to a remote - repository. By default the remote gets all dependencies - (both tgish and non-tgish) and bases pushed to. + pushes a TopGit-controlled topic branch - the current branch, if + you don't specify which - to a remote repository. By default, + the remote gets all the dependencies (both TopGit-controlled and + non-TopGit-controlled) and bases pushed to it too. tg base ~~~~~~~ @@ -549,14 +555,15 @@ tg base tg log ~~~~~~ - Prints the git log of the named topgit branch. + Prints the git log of the named topgit branch - or the current + branch, if you don't specify a name. - Note: if you have merged changes from a different repository, this + NOTE: if you have merged changes from a different repository, this command might not list all interesting commits. tg prev ~~~~~~~ - Outputs the direct dependencies for the current or named patch. + Outputs the direct dependencies for the current or named branch. Options: -i show dependencies based on index instead of branch @@ -564,8 +571,8 @@ tg prev tg next ~~~~~~~ - Outputs all patches which directly depend on the current or - named patch. + Outputs all branches which directly depend on the current or + named branch. Options: -i show dependencies based on index instead of branch @@ -576,52 +583,52 @@ TODO: tg rename IMPLEMENTATION -------------- -TopGit stores all the topic branches in the regular refs/heads/ -namespace, (we recommend to mark them with the 't/' prefix). -Except that, TopGit also maintains a set of auxiliary refs in -refs/top-*. Currently, only refs/top-bases/ is used, containing -the current _base_ of the given topic branch - this is basically -a merge of all the branches the topic branch depends on; it is -updated during `tg update` and then merged to the topic branch, -and it is the base of a patch generated from the topic branch by -`tg patch`. - -All the metadata is tracked within the source tree and history -of the topic branch itself, in .top* files; these files are kept -isolated within the topic branches during TopGit-controlled merges -and are of course omitted during `tg patch`. The state of these -files in base commits is undefined; look at them only in the topic -branches themselves. Currently, two files are defined: - - .topmsg: Contains the description of the topic branch -in a mail-like format, plus the author information, -whatever Cc headers you choose or the post-three-dashes message. -When mailing out your patch, basically only few extra headers -mail headers are inserted and the patch itself is appended. -Thus, as your patches evolve, you can record nuances like whether -the particular 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 -updated) merge of these branches will be the "base" of your topic -branch. DO NOT EDIT THIS FILE MANUALLY!!! If you do so, you need -to know exactly what are you doing, since this file must stay in -sync with the Git history information, otherwise very bad things -will happen. +TopGit stores all the topic branches in the regular 'refs/heads/' +namespace (so we recommend distinguishing them with the 't/' prefix). +Apart from that, TopGit also maintains a set of auxiliary refs in +'refs/top-*'. Currently, only refs/top-bases/ is used, containing the +current _base_ of the given topic branch - this is basically a merge of +all the branches the topic branch depends on; it is updated during `tg +update` and then merged to the topic branch, and it is the base of a +patch generated from the topic branch by `tg patch`. + +All the metadata is tracked within the source tree and history of the +topic branch itself, in .top* files; these files are kept isolated +within the topic branches during TopGit-controlled merges and are of +course omitted during `tg patch`. The state of these files in base +commits is undefined; look at them only in the topic branches +themselves. Currently, two files are defined: + + '.topmsg': Contains the description of the topic branch in a +mail-like format, plus the author information, whatever Cc headers you +choose or the post-three-dashes message. When mailing out your patch, +basically only a few extra mail headers are inserted and then the patch +itself is appended. Thus, as your patches evolve, you can record +nuances like whether the particular 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.*' git config +options. + + '.topdeps': Contains the one-per-line list of branches this +branch depends on, pre-seeded by `tg create`. A (continuously updated) +merge of these branches will be the "base" of your topic branch. + +IMPORTANT: DO NOT EDIT '.topdeps' MANUALLY!!! If you do so, you need to +know exactly what are you doing, since this file must stay in sync with +the Git history information, otherwise very bad things will happen. TopGit also automagically installs a bunch of custom commit-related -hooks that will verify if you are committing the .top* files in sane -state. It will add the hooks to separate files within the hooks/ -subdirectory and merely insert calls of them to the appropriate hooks -and make them executable (but make sure the original hooks code -is not called if the hook was not executable beforehand). +hooks that will verify whether you are committing the '.top*' files in a +sane state. It will add the hooks to separate files within the 'hooks/' +subdirectory, and merely insert calls to them to the appropriate hooks +and make them executable (but will make sure the original hook's code is +not called if the hook was not executable beforehand). -Another automagically installed piece is .git/info/attributes specifier -for an 'ours' merge strategy for the files .topmsg and .topdeps, and -the (intuitive) 'ours' merge strategy definition in .git/config. +Another automagically installed piece is a '.git/info/attributes' +specifier for an 'ours' merge strategy for the files '.topmsg' and +'.topdeps', and the (intuitive) 'ours' merge strategy definition in +'.git/config'. REMOTE HANDLING @@ -639,31 +646,34 @@ There are two somewhat contradictory design considerations here: repository (b) Having a self-contained topic system in local refs space -To us, (a) does not appear to be very convincing, while (b) is quite desirable -for 'git-log topic' etc. working, and increased conceptual simplicity. - -Thus, we choose to instantiate all the topic branches of given remote locally; -this is performed by 'tg remote --populate'. -'tg update' will also check if a branch can be updated from its corresponding -remote branch. The logic is somewhat involved if we should DTRT. -First, we update the base, handling the remote branch as if it was the first -dependency; thus, conflict resolutions made in the remote branch will be -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. +To us, (a) does not appear to be very convincing, while (b) is quite +desirable for 'git-log topic' etc. working, and increased conceptual +simplicity. + +Thus, we choose to instantiate all the topic branches of given remote +locally; this is performed by `tg remote --populate`. `tg update` will +also check if a branch can be updated from its corresponding remote +branch. The logic needs to be somewhat involved if we are to "do the +right thing". First, we update the base, handling the remote branch as +if it was the first dependency; thus, conflict resolutions made in the +remote branch will be carried over to our local base automagically. +Then, the base is merged into the remote branch and the result is merged +to the local branch - again, to carry over remote conflict resolutions. +In the future, this order might be adjustable on a per-update basis, in +case local changes happen to be diverging more than the remote ones. + +All commands by default refer to the remote that `tg remote --populate` +was called on the last time (stored in the 'topgit.remote' git +configuration variable). You can manually run any command with a +different base remote by passing '-r REMOTE' _before_ the subcommand +name. POINTERS -------- -The following references are useful to understand the development of topgit and -its subcommands. +The following references are useful to understand the development of +topgit and its subcommands. tg depend: http://lists-archives.org/git/688698-add-list-and-rm-sub-commands-to-tg-depend.html diff --git a/create-help.sh b/create-help.sh index fbd9a09..1b82162 100755 --- a/create-help.sh +++ b/create-help.sh @@ -3,7 +3,7 @@ # Create the tg-foo.txt files which contain help for the tg-foo command. if [ $# -ne 1 ] ; then - echo "Usage: $0 tgcommand" 1>&2 + echo "Usage: $0 " 1>&2 exit 1 fi diff --git a/tg-create.sh b/tg-create.sh index 617031b..2215e2c 100644 --- a/tg-create.sh +++ b/tg-create.sh @@ -18,7 +18,7 @@ while [ -n "$1" ]; do -r) rname="$1"; shift;; -*) - echo "Usage: tg [...] create NAME [DEPS...|-r RNAME]" >&2 + echo "Usage: tg [...] create [ [...|-r ] ]" >&2 exit 1;; *) if [ -z "$name" ]; then diff --git a/tg-delete.sh b/tg-delete.sh index 64d2057..5f7e82d 100644 --- a/tg-delete.sh +++ b/tg-delete.sh @@ -15,7 +15,7 @@ while [ -n "$1" ]; do -f) force=1;; -*) - echo "Usage: tg [...] delete [-f] NAME" >&2 + echo "Usage: tg [...] delete [-f] " >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-depend.sh b/tg-depend.sh index 474ccda..cf78946 100644 --- a/tg-depend.sh +++ b/tg-depend.sh @@ -8,7 +8,7 @@ name= usage() { - echo "Usage: tg [...] depend add NAME" >&2 + echo "Usage: tg [...] depend add " >&2 exit 1 } diff --git a/tg-export.sh b/tg-export.sh index 72320af..e28871a 100644 --- a/tg-export.sh +++ b/tg-export.sh @@ -43,7 +43,7 @@ while [ -n "$1" ]; do --linearize) driver=linearize;; -*) - echo "Usage: tg [...] export ([--collapse] NEWBRANCH | [-b BRANCH1,BRANCH2...] --quilt DIRECTORY | --linearize NEWBRANCH)" >&2 + echo "Usage: tg [...] export ([--collapse] | [-b ...] --quilt | --linearize )" >&2 exit 1;; *) [ -z "$output" ] || die "output already specified ($output)" diff --git a/tg-files.sh b/tg-files.sh index 507efcb..67f6ca0 100644 --- a/tg-files.sh +++ b/tg-files.sh @@ -16,7 +16,7 @@ while [ -n "$1" ]; do [ -z "$head_from" ] || die "-i and -w are mutually exclusive" head_from="$arg";; -*) - echo "Usage: tg [...] files [-i | -w] [NAME]" >&2 + echo "Usage: tg [...] files [-i | -w] []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-import.sh b/tg-import.sh index a8d3be5..cc345b0 100644 --- a/tg-import.sh +++ b/tg-import.sh @@ -22,7 +22,7 @@ while [ -n "$1" ]; do -s) single="$1"; shift;; -*) - echo "Usage: tg [...] import [-d BASE_BRANCH] {[-p PREFIX] RANGE...|-s NAME COMMIT}" >&2 + echo "Usage: tg [...] import [-d ] ([-p ] ... | -s )" >&2 exit 1;; *) ranges="$ranges $arg";; diff --git a/tg-info.sh b/tg-info.sh index 10e257e..0ff82d1 100644 --- a/tg-info.sh +++ b/tg-info.sh @@ -12,7 +12,7 @@ while [ -n "$1" ]; do arg="$1"; shift case "$arg" in -*) - echo "Usage: tg [...] info [NAME]" >&2 + echo "Usage: tg [...] info []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-log.sh b/tg-log.sh index 8a8d527..4a57dc2 100644 --- a/tg-log.sh +++ b/tg-log.sh @@ -15,7 +15,7 @@ while [ -n "$1" ]; do --) break;; -*) - echo "Usage: tg [...] log [NAME] [-- GIT LOG OPTIONS...]" >&2 + echo "Usage: tg [...] log [] [-- ...]" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-mail.sh b/tg-mail.sh index 17ce02c..3a5c998 100644 --- a/tg-mail.sh +++ b/tg-mail.sh @@ -21,7 +21,7 @@ while [ -n "$1" ]; do -r) in_reply_to="$1"; shift;; -*) - echo "Usage: tg [...] mail [-s SEND_EMAIL_ARGS] [-r REFERENCE_MSGID] [-i | -w] [NAME]" >&2 + echo "Usage: tg [...] mail [-s ] [-r ] [-i | -w] []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-next.sh b/tg-next.sh index 93dd5b5..5817bba 100644 --- a/tg-next.sh +++ b/tg-next.sh @@ -17,7 +17,7 @@ while [ -n "$1" ]; do [ -z "$head_from" ] || die "-i and -w are mutually exclusive" head_from="$arg";; -*) - echo "Usage: tg next [-i | -w] [NAME]" >&2 + echo "Usage: tg next [-i | -w] []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-patch.sh b/tg-patch.sh index 9def6e5..f23a1ac 100644 --- a/tg-patch.sh +++ b/tg-patch.sh @@ -17,7 +17,7 @@ while [ -n "$1" ]; do [ -z "$head_from" ] || die "-i and -w are mutually exclusive" head_from="$arg";; -*) - echo "Usage: tg [...] patch [-i | -w] [NAME]" >&2 + echo "Usage: tg [...] patch [-i | -w] []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-prev.sh b/tg-prev.sh index 1f1e0c1..d4f778d 100644 --- a/tg-prev.sh +++ b/tg-prev.sh @@ -17,7 +17,7 @@ while [ -n "$1" ]; do [ -z "$head_from" ] || die "-i and -w are mutually exclusive" head_from="$arg";; -*) - echo "Usage: tg next [-i | -w] [NAME]" >&2 + echo "Usage: tg next [-i | -w] []" >&2 exit 1;; *) [ -z "$name" ] || die "name already specified ($name)" diff --git a/tg-push.sh b/tg-push.sh index f4652f5..efaffc3 100644 --- a/tg-push.sh +++ b/tg-push.sh @@ -18,7 +18,7 @@ while [ -n "$1" ]; do --tgish-only) tgish_deps_only=true;; -h|--help) - echo "Usage: tg push [--dry-run] [--no-deps] [--tgish-only] [-r remote] branch*" + echo "Usage: tg push [--dry-run] [--no-deps] [--tgish-only] [-r ] [...]" exit 0;; -r) remote="$1" diff --git a/tg-remote.sh b/tg-remote.sh index 61774d7..ab80863 100644 --- a/tg-remote.sh +++ b/tg-remote.sh @@ -15,7 +15,7 @@ while [ -n "$1" ]; do --populate) populate=1;; -*) - echo "Usage: tg [...] remote [--populate] [REMOTE]" >&2 + echo "Usage: tg [...] remote [--populate] []" >&2 exit 1;; *) name="$arg";; diff --git a/tg-update.sh b/tg-update.sh index 10d4c0f..6cb8ff3 100644 --- a/tg-update.sh +++ b/tg-update.sh @@ -17,7 +17,7 @@ while [ -n "$1" ]; do -a) all=1;; -*) - echo "Usage: tg [...] update [-a] [NAME|PATTERN ...]" >&2 + echo "Usage: tg [...] update [-a] [ | ...]" >&2 exit 1;; *) if [ -z "$all" ]; then diff --git a/tg.sh b/tg.sh index 3438391..755324b 100644 --- a/tg.sh +++ b/tg.sh @@ -370,7 +370,7 @@ do_help() done echo "TopGit v$TG_VERSION - A different patch queue manager" - echo "Usage: tg [-r REMOTE] ($cmds|help) ..." + echo "Usage: tg ( help [] | [-r ] ($cmds) ...)" elif [ -r "@cmddir@"/tg-$1 ] ; then setup_pager @cmddir@/tg-$1 -h 2>&1 || :