TODO: tg patch -i to base at index instead of branch,
-w for working tree
+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.
+
+ It takes a mandatory 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 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).
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: -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 update
~~~~~~~~~
Update the current topic branch wrt. changes in the branches
- it depends on. This is made in two phases - first,
+ 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.
+ then the base is merged into the topic branch.
+ The output will guide you in case of conflicts.
In case your dependencies are not up-to-date, tg update
will first recurse into them and update these.
TODO: Some infrastructure for sharing topic branches between
repositories easily
TODO: tg depend for adding/removing dependencies smoothly
+TODO: tg rename
IMPLEMENTATION
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.
+
+
+REMOTE HANDLING
+---------------
+
+There are three issues with accessing topic branches in remote repositories:
+
+ (i) Fetching/pushing accurate picture of the remote topic branch setup
+ (ii) Referring to remote topic branches from your local repository
+ (iii) Developing some of the remote topic branches locally
+
+(ii) and (iii) are fairly interconnected problems, while (i) is largely
+independent. The issue is to accurately reflect the current state of the
+quickly changing topic branches set - this can be easily done
+with the current facilities like 'git remote prune' and 'git push --mirror' -
+and to properly upload also the bases of the topic branches.
+For this, we need to modify the fetch/push refspecs to also include
+the refs/top-bases/ ref namespace; we shall provide a special 'tg remote'
+command to set up an existing remote for TopGit usage.
+
+About (ii) and (iii), there are two somewhat contradicting design
+considerations:
+
+ (a) Hacking on multiple independent TopGit remotes in a single
+ 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, 'git push' automatically creating
+self-contained topic system in the remote repository, 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.
~ian / topgit.git / blobdiff