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).
tg export
~~~~~~~~~
- Create a new branch containing tidied-up history
- of the current topic branch and its dependencies,
- suitable for pull by upstream - each topic branch
- corresponds to a single commit 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 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:
`- 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 requires one mandatory argument: the name of the 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.
- Usage: tg export BRANCH
+ 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: --quilt and --mbox options for other modes of operation
+ 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 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