X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topgit.git;a=blobdiff_plain;f=README;h=dec299f009892922b13c8f199fd53a12a678603e;hp=8be0d17ec0e005ce08693505097e4fa9e38d9131;hb=8d92943bcdb6eea3819dce28d2ff48dd8a061b31;hpb=7e24a4aafda160b0715436034d5c8bf6f62ad8bd diff --git a/README b/README index 8be0d17..dec299f 100644 --- a/README +++ b/README @@ -244,6 +244,10 @@ tg delete only empty branch (base == head); use '-f' to remove non-empty branch. + 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 @@ -284,8 +288,9 @@ tg patch tg patch will be able to automatically send the patches by mail or save them to files. (TODO) - TODO: tg patch -i to base at index instead of branch, - -w for working tree + Options: + -i base patch generation on index instead of branch + -w base patch generation on working tree instead of branch tg mail ~~~~~~~ @@ -303,6 +308,13 @@ tg mail The '-r' parameter with 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 + + git config sendemail.confirm always + + to let `git send-email` ask for confirmation before sending any mail. + TODO: 'tg mail patchfile' to mail an already exported patch TODO: mailing patch series TODO: specifying additional options and addresses on command @@ -339,6 +351,17 @@ tg summary 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. + + The --deps option outputs dependency informations between + branches in a machine-readable format. Feed this to "tsort" + to get the output from --sort. + TODO: Speed up by an order of magnitude TODO: Text graph view @@ -350,11 +373,12 @@ tg export in the cleaned up history (corresponding basically exactly to `tg patch` output for the topic branch). - The command has two possible outputs now - either a Git branch - with the collapsed 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 + 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: @@ -377,6 +401,21 @@ tg export `- t/bar/good <,-------------------'/ `- t/baz ---------------------' + In case of 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. + + Note that you might get conflicts during linearization because the + patches are reordered to get a linear history. + In case of the quilt mode, master$ tg export --quilt for-linus @@ -409,14 +448,23 @@ tg export 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) + 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. slashed are substituted by + underscores). With '--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) 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 TODO: -a option to export all branches - TODO: For quilt exporting, use a temporary branch and remove it when - done - this would allow producing conflict-less series + TODO: For quilt exporting, export the linearized history created in a + temporary branch---this would allow producing conflict-less + series tg import ~~~~~~~~~ @@ -435,13 +483,15 @@ tg import tg update ~~~~~~~~~ - Update the current topic branch wrt. changes in the branches - it depends on and remote branches. + Update the current or specified topic branch wrt. changes in the + branches it 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. + After the update the current branch is the specified one. + In case your dependencies are not up-to-date, tg update will first recurse into them and update these. @@ -454,6 +504,27 @@ tg update TODO: tg update -a for updating all topic 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. + +tg base +~~~~~~~ + Prints the base commit of the current topic branch. Silently + exits with exit code 1 if you are not working on a TopGit + branch. The following command can be useful to get a summary + of the work you have made on a topic branch: + + git log --first-parent --no-merges `tg base`.. + + (Note: if you have shared the TopGit branch, the above command + only lists the commits that were made in the current + repository, so you will not see work done by your + collaborators.) + + TODO: tg rename @@ -553,3 +624,13 @@ 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. + + +POINTERS +-------- + +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