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
-----
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.
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
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
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
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
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