RATIONALE
---------
-Why not use something like StGIT or Guilt or rebase -i for that?
-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 index efectively when using StGIT. But more
-importantly, these tools horribly fail in the face of distributed
-environment.
-
-TopGit has been designed around three main tenents:
+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 efectively when using StGIT. But more importantly,
+these tools horribly fail in the face of 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.
(ii) TopGit is anxious about _keeping_ your history. It will
-never rewrite your history and all metadata are also tracked by Git,
-smoothly and non-obnoxiously. It is useful if there is 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.
+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
simpler, conceptually. If you just want to make a linear purely-local
patch queue, deferring to StGIT instead might make more sense.
- (ii) While keeping your history anxiously, in some extreme
-cases the TopGit-generated history graph will perhaps be a little
-too complex. ;-)
+ (ii) When using TopGit, your history can get a little hairy
+over time, especially with all the merges rippling through. ;-)
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
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!
tg: you will want to switch to a different branch.
$ ..resolve..
$ git commit
+ $ tg create
tg: Resuming t/whatever setup...
- $ tg create t/whatever
$ ..hack..
$ git commit
~~~~~~~~~
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.
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
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
tg summary
~~~~~~~~~~
Show overview of all TopGit-tracked topic branches and their
- up-to-date status ('D' marks that it is out-of-date wrt. its
- dependencies, 'B' marks that it is out-of-date wrt. its base).
+ up-to-date status ('0' marks that it introduces no own changes,
+ '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).
+
+ TODO: Speed up by an order of magnitude
+ TODO: Graph view
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
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
~ian / topgit.git / blobdiff