X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topgit.git;a=blobdiff_plain;f=README;h=8299027e97ac579823695cdd6e3b67566a8d10f6;hp=b58a1b43e8f7383ed53b60464886d6efaf08de1a;hb=459c340fd5ac765ff1e5d82895b59b53b028aaca;hpb=6d1f60429c7c8a769e4e78a0a5bbc460dea7248a diff --git a/README b/README index b58a1b4..8299027 100644 --- a/README +++ b/README @@ -250,10 +250,26 @@ tg patch 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). @@ -329,14 +345,21 @@ tg export 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. @@ -346,6 +369,7 @@ tg update TODO: Some infrastructure for sharing topic branches between repositories easily TODO: tg depend for adding/removing dependencies smoothly +TODO: tg rename IMPLEMENTATION @@ -394,3 +418,50 @@ is not called if the hook was not executable beforehand). 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.