X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=topgit.git;a=blobdiff_plain;f=README;h=35a9f98b773686e9a9b1301ad61edb9b0c122ca9;hp=f914647ed7b59ff0798062f385de68caef1cf435;hb=3051faceb5eb73f328a76d790a23fa7a9c71b427;hpb=2e60e0028aa2902a421d166b8803ec640af8471b diff --git a/README b/README index f914647..35a9f98 100644 --- a/README +++ b/README @@ -184,6 +184,24 @@ SYNOPSIS tg: Updating base with t/gitweb/nifty-links changes... tg: Updating t/whatever against new base... + ## Clone a TopGit-controlled repository + $ git clone URL repo + $ cd repo + $ tg remote --populate origin + ... + $ git fetch + $ tg update + + ## Add a TopGit remote to a repository and push to it + $ git remote add foo URL + $ tg remote foo + $ git push foo + + ## Update from a non-default TopGit remote + $ git fetch foo + $ tg -r foo summary + $ tg -r foo update + USAGE ----- @@ -203,7 +221,10 @@ tg create 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. @@ -212,6 +233,10 @@ tg create it will detect that you are on a topic branch base ref and resume the topic branch creation operation. + In an alternative use case, if '-r BRANCH' is given instead + of dependency list, the topic branch is created based on + the given remote branch. + tg delete ~~~~~~~~~ Remove a TopGit-controlled topic branch of given name @@ -228,6 +253,19 @@ tg delete TODO: '-a' to delete all empty branches, depfix, revert +tg depend +~~~~~~~~~ + Change dependencies of a TopGit-controlled topic branch. + This should have several subcommands, but only 'add' is + supported right now. + + The 'add' subcommand takes an argument of a topic branch + to be added, adds it to '.topdeps', performs a commit and + then updates your topic branch accordingly. If you want to + do other things related to the dependency addition, like + adjusting '.topmsg', prepare them in the index before + calling 'tg depend add'. + tg info ~~~~~~~ Show a summary information about the current or specified @@ -247,35 +285,172 @@ tg patch TODO: tg patch -i to base at index instead of branch, -w for working tree +tg mail +~~~~~~~ + Send a patch from the current or specified topic branch as + email. + + Takes the patch given on the command line and emails it out. + Destination addresses such as To, Cc and Bcc are taken from the + patch header. + + Since it actually boils down to `git send-email` please refer to + its documentation for details on how to setup email for git. + You can pass arbitrary options to this command through the + '-s' parameter, but you must double-quote everything. + + TODO: 'tg mail patchfile' to mail an already exported patch + TODO: mailing patch series + TODO: specifying additional options and addresses on command + line + +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. (Do NOT use 'git push --all' + for your pushes - plain 'git push' will do the right thing.) + + 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). + This can take long time to accurately determine all the relevant + information about each branch; you can pass '-t' to get just + terse list of topic branch names quickly. + 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. + + With '--quilt', you can also pass '-b' parameter followed by + a comma-separated explicit list of branches to export. This + mode of operation is currently not supported with collapse. + + 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: For quilt exporting, use a temporary branch and remove it when + done - this would allow producing conflict-less series + +tg import +~~~~~~~~~ + Import commits within the given revision range into TopGit, + creating one topic branch per commit, the dependencies forming + a linear sequence starting on your current branch (or a branch + specified by the '-d' parameter). + + The branch names are auto-guessed from the commit messages + and prefixed by t/ by default; use '-p PREFIX' to specify + an alternative prefix (even an empty one). + + Alternatively, you can use the '-s NAME' parameter to specify + the name of target branch; the command will then take one more + argument describing a single commit to import. + 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. + If a remote branch update brings dependencies on branches + not yet instantiated locally, you can either bring in all + the new branches from the remote using 'tg remote --populate' + or only pick out the missing ones using 'tg create -r' + ('tg summary' will point out branches with incomplete + dependencies by showing an '!' near to them). + TODO: tg update -a for updating all topic branches -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 @@ -306,11 +481,16 @@ mail headers are inserted and the patch itself is appended. 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 updated) merge of these branches will be the "base" of your topic -branch. +branch. DO NOT EDIT THIS FILE MANUALLY!!! If you do so, you need +to know exactly what are you doing, since this file must stay in +sync with the Git history information, otherwise very bad things +will happen. TopGit also automagically installs a bunch of custom commit-related hooks that will verify if you are committing the .top* files in sane @@ -322,3 +502,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.