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: 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
+ 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 import
+~~~~~~~~
+ Import the commits between the given revision range into
+ a topgit managed branch
+
+ Usage: tg import rev1..rev2
+
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 collapse for creating a one-commit-per-patch tidied up
- history (for pulling by upstream)
+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