From Previous to Next

For this section, consider the following patch series, to be applied in numerical order as shown:

0001-F_first-patch.diff
0002-G_second-builds-on-F.diff
0003-H_third-builds-on-G.diff
0004-I_fourth-builds-on-H.diff
0005-J_fifth-builds-on-I.diff
0006-K_sixth-builds-on-J.diff
0007-L_last-patch-needs-K.diff

If these were applied to some commit in a Git repository, say commit "A" then a history that looks like this would be created:

A---F---G---H---I---J---K---L

Where the parent of commit "F" is "A" and so on to where the parent of commit "L" is commit "K".

If that commit history, from A through L, was then imported into TopGit, one TopGit branch would be created corresponding to each of the commits F through L. This way, for example, if the fourth patch in the series (0004-I_...diff) needs work, the TopGit branch corresponding to its patch can be checked out and changes made and then a new version of its patch created (using tg patch) without disturbing the other patches in the series and when tg update is run, the patches that "follow" the fourth patch (i.e. 5, 6 and 7) will have their corresponding TopGit branches automatically updated to take into account the changes made to the fourth patch.

+-------------------------------+
| Unmodified "upstream" source  |
| files represented with "A"    |
+-------------------------------+

+--------------------------+----+
| Patch 0001 represented by "F" |
+-------------------------------+
| Unmodified "upstream" source  |
| files represented with "A"    |
+-------------------------------+

+--------------------------+----+
| Patch 0004 represented by "I" |
+--------------------------+----+
| Patch 0003 represented by "H" |
+--------------------------+----+
| Patch 0002 represented by "G" |
+--------------------------+----+
| Patch 0001 represented by "F" |
+-------------------------------+
| Unmodified "upstream" source  |
| files represented with "A"    |
+-------------------------------+

tg help

tg help [-w] [<command>]

Options:

  -w                  view help in browser

Our sophisticated integrated help facility. Mostly duplicates what is below:

# to list commands:
$ tg help
# to get help for a particular command:
$ tg help <command>
# to get help for a particular command in a browser window:
$ tg help -w <command>
# to get help on TopGit itself
$ tg help tg
# to get help on TopGit itself in a browser
$ tg help -w tg

tg status

tg st[atus] [-v] [--exit-code]

Our sophisticated status facility. Similar to Git's status command but shows any in-progress update that's awaiting a merge resolution or any other on-going TopGit activity (such as a branch creation).

With a single --verbose (or -v) option include a short status display for any dirty (but not untracked) files. This also causes all non file status lines to be prefixed with "## ".

With two (or more) --verbose (or -v) options, additionally show full symbolic ref names and unabbreviated hash values.

With the --exit-code option the exit code will be non-zero if any TopGit or Git operation is currently in progress or the working directory is unclean.

tg create

tg [...] create [<option>...] [<name> [<dep>...]]

tg [...] create [<option>...] --base <name> [<committish>]

tg [-r <remote>] create [<option>...] <name> -r [<rbranch>]

Options:

  --no-deps           alternate spelling of '--base'

  --quiet / -q        suppress most informational messages

  --message <msg>     replace default commit message

  -m <msg>            (default message is "tg create <name>")

  --file <file>       replace default commit message

  -F <file>           with contents of <file>

  --topmsg <msg>      use <msg> as .topmsg and skip editor

  --tm <msg>          (<msg> may be reformatted with a warning)

  --topmsg-file <f>   use contents of file <f> as --topmsg

  --tF <file>         alias for --topmsg-file <file>

  --force / -f        ignore tag with same name as new branch

  --no-edit           do not run the editor on default .topmsg

  --no-commit / -n    stop before actually making the commit

  --no-update         do not run 'tg update' (implied by -n)

Create a new TopGit-controlled topic branch of the given name (required argument) and switch to it. If no dependencies are specified (by extra arguments passed after the first one), the current branch is assumed to be the only dependency.

By default tg create opens an editor on the new .topmsg file and then commits the new .topmsg and .topdeps files automatically with a suitable default commit message.

The commit message can be changed with the -m (or --message) or -F (or --file) option. The automatic commit can be suppressed by using the --no-commit (or -n) option. Running the editor on the new .topmsg file can be suppressed by using --no-edit (which does NOT suppress the automatic commit unless --no-commit is also given) or by providing an explicit value for the new .topmsg file using the --topmsg or --topmsg-file option. In any case the .topmsg content will be automatically reformated to have a Subject: header line if needed.

If the format.signoff config variable (see git help config) has been set to true then the Signed-off-by: header line added to the end of the initial version of the .topmsg file will be uncommented by default. Otherwise it will still be there but will be commented out and will be automatically stripped if no action is taken to remove the comment character.

If more than one dependency is listed an automatic tg update runs after the branch has been created to merge in the additional dependencies and bring the branch up-to-date. This can be suppressed with the --no-commit option (which also suppresses the initial commit) or the --no-update option (which allows the initial commit while suppressing only the update operation portion).

Previous versions of TopGit behaved as though both the --no-edit and --no-commit options were always given on the command line.

The default behavior has been changed to promote a separation between commits that modify .topmsg and/or .topdeps and commits that modify other files. This facilitates cleaner cherry picking and other patch maintenance activities.

You should edit the patch description (contained in the .topmsg file) as appropriate. It will already contain some prefilled bits. You can set the topgit.to, topgit.cc and topgit.bcc git configuration variables (see git help config) in order to have tg create add these headers with the given default values to .topmsg before invoking the editor. If the configuration variable topgit.subjectPrefix is set its value will be inserted between the initial [ and the word PATCH in the subject line (with a space added before the word PATCH of course).

The main task of tg create is to set up the topic branch base from the dependencies. This may fail due to merge conflicts if more than one dependency is given. In that case, after you commit the conflict resolution, you should call tg update --continue to finish merging the dependencies into the new topic branch base.

With the --base (aka --no-deps) option at most one dependency may be listed which may be any valid committish (instead of just refs/heads/...) and the newly created TopGit-controlled branch will have an empty .topdeps file. This may be desirable in order to create a TopGit-controlled branch that has no changes of its own and serves merely to mark the common dependency that all other TopGit-controlled branches in some set of TopGit-controlled branches depend on. A plain, non-TopGit-controlled branch can be used for the same purpose, but the advantage of a TopGit-controlled branch with no dependencies is that it will be pushed with tg push, it will show up in the tg summary and tg info output with the subject from its .topmsg file thereby documenting what it's for and finally it can be set up with tg create -r and/or tg remote --populate to facilitate sharing.

For example, tg create --base t/release v2.1 will create a TopGit- controlled t/release branch based off the v2.1 tag that can then be used as a base for creation of other TopGit-controlled branches. Then when the time comes to move the base for an entire set of changes up to v2.2 the command tg update --base t/release v2.2 can be used followed by tg update --all.

Using --base it's also possible to use tg create on an unborn branch (omit the dependency name or specify HEAD). The unborn branch itself can be made into the new TopGit branch (rather than being born empty and then having the new TopGit branch based off that) by specifying HEAD as the new branch's name (which is probably what you normally want to do in this case anyway so you can just run tg create --base HEAD to accomplish that).

In an alternative use case, if -r <rbranch> is given instead of a dependency list, the topic branch is created based on the given remote branch. With just -r the remote branch name is assumed to be the same as the local topic branch being created. Since no new commits are created in this mode (only two refs will be updated) the editor will never be run for this use case. Note that no other options may be combined with -r although a global -r option can be used to alter which remote <rbranch> refers to.

The --quiet (or -q) option suppresses most informational messages.

tg delete

tg [...] delete [-f] <name>

Remove a TopGit-controlled topic branch of the given name (required argument). Normally, this command will remove only an empty branch (base == head) without dependents; use -f to remove a non-empty branch or a branch that is depended upon by another branch.

The -f option is also useful to force removal of a branch's base, if you used git branch -D B to remove branch B, and then certain TopGit commands complain, because the base of branch B is still there.

Normally tg delete will refuse to delete the current branch. However, giving -f twice (or more) will force it to do so but it will first detach your HEAD.

IMPORTANT: Currently, this command will NOT remove the branch from the dependency list in other branches. You need to take care of this manually. This is even more complicated in combination with -f – in that case, you need to manually unmerge the removed branch's changes from the branches depending on it.

The same --stash and --no-stash options are accepted with the same exact semantics as for tg update.

See also tg annihilate.

TODO: -a to delete all empty branches, depfix, revert

tg annihilate

tg [...] annihilate [-f] [--no-update] [<name>]

Make a commit on the current or given TopGit-controlled topic branch that makes it equal to its base, including the presence or absence of .topmsg and .topdeps. Annihilated branches are not displayed by tg summary, so they effectively get out of your way. However, the branch still exists, and tg push will push it (except if given the -a option). This way, you can communicate that the branch is no longer wanted.

When annihilating a branch that has dependents (i.e. branches that depend on it), those dependents have the dependencies of the branch being annihilated added to them if they do not already have them as dependencies. Essentially the DAG is repaired to skip over the annihilated branch.

Normally, this command will remove only an empty branch (base == head, except for changes to the .top* files); use -f to annihilate a non-empty branch.

After completing the annihilation itself, normally tg update is run on any modified dependents. Use the --no-update option to suppress running tg update.

The same --stash and --no-stash options are accepted with the same exact semantics as for tg update.

tg depend

tg [...] depend add [--no-update | --no-commit] <name>...

Change the 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 naming 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, use the option --no-commit. Adding the --no-update (or --no-commit) option will suppress the tg update normally performed after committing the change.

It is safe to run tg depend add in a dirty worktree, but the normally performed tg update will be suppressed in that case (even if neither --no-update nor --no-commit is given).

You have enabled git rerere haven't you?

TODO: Subcommand for removing dependencies, obviously

tg files

tg [...] files [-i | -w] [<name>]

Options:

  -i                  use TopGit metadata from index instead of HEAD branch

  -w                  use metadata from working directory instead of branch

List files changed by the current or specified topic branch.

tg info

tg [...] info [-i | -w] [--heads | --leaves | --series[=<head>]] [<name>]

tg [...] info [-i | -w] [--deps | --dependencies | --dependents] [<name>]

Options:

  -i                  use TopGit metadata from index instead of HEAD branch

  -w                  use metadata from working directory instead of branch

Show summary information about the current or specified topic branch.

Numbers in parenthesis after a branch name such as "(11/3 commits)" indicate how many commits on the branch (11) and how many of those are non-merge commits (3).

With --verbose (or -v) include a list of dependents (i.e. other branches that depend on this one). Another --verbose annotates them with "[needs merge]" if the current tip of branch for which info is being shown has not yet been merged into the base of the dependent. Two --verbose options also cause annihilated dependencies to be shown in the "Depends:" list.

Alternatively, if --heads is used then which of the independent TopGit branch heads (as output by tg summary --topgit-heads) logically contains the specified commit (which may be any committish -- defaults to HEAD if not given). Zero or more results will be output. Note that "logically" means with regard to the TopGit dependency relationships as established by the .topdeps file(s). It's the answer that would be given when all the TopGit branches are up-to-date (even though they need not be to use this option) and the git branch --contains command is run and the output then filtered to only those branches that appear in tg summary --topgit-heads. This computation may require several seconds on complex repositories.

If --leaves is used then the unique list of leaves of the current or specified topic branch is shown as one fully-qualified ref per line. Duplicates are suppressed and a tag name will be used when appropriate. A "leaf" is any dependency that is either not a TopGit branch or is the base of a non-annihilated TopGit branch with no non-annihilated dependencies.

The --deps option shows non-annihilated TopGit dependencies of the specified branch (default is HEAD). (It can also be spelled out as --dependencies for the pedantically inclined.)

The --dependents option shows non-annihilated TopGit dependents (i.e. branches that depend on the specified branch). The default branch to operate on is again HEAD.

A linearized patch series can only be automatically created for a TopGit topic branch (including its recursive dependencies) when exactly one line is output by tg info --leaves <topic-branch>.

With --series the list of TopGit branches in the order they would be linearized into a patch series is shown along with the description of each branch. If the branch name passed to tg info is not the last branch in the series a marker column will be provided to quickly locate it in the list. This same option can be used with tg checkout.

Some patches shown in the list may not actually end up introducing any changes if exported and will therefore end up being omitted. The 0 indicator in tg summary output can help to identify some of these.

The patches shown in the series in the order they are shown form the basis for the tg next and tg prev operations with the first patch shown being considered the first and so on up to the last.

tg patch

tg [...] patch [-q] [-i | -w] [--binary] [<name>] [--] [<git-diff-tree-option>...]

Generate a patch from the current or specified topic branch. This means that the diff between the topic branch base and head (latest commit) is shown, appended to the description found in the .topmsg file.

The patch is simply dumped to stdout. In the future, tg patch will be able to automatically send the patches by mail or save them to files. (TODO)

Options:

-i	base patch generation on index instead of branch
-w	base patch generation on working tree instead of branch
--binary	pass --binary to git diff-tree to enable generation of binary patches
--quiet	be quiet (aka -q) about missing and unfixed From:
--from	make sure patch has a From: line, if not add one
--from=<a>	<a> or Signed-off-by value or ident value; git am really gets unhappy with patches missing From: lines; will NOT replace an existing non-empty From: header
--no-from	leave all From: lines alone, missing or not (default)
--diff-opt	options after the branch name (and an optional --) are passed directly to git diff-tree

In order to pass a sole explicit -w through to git diff-tree it must be separated from the tg options by an explicit --. Or it can be spelled as --ignore-all-space to distinguuish it from tg's -w option.

If the config variable topgit.from is set to a boolean it can be used to enable or disable the --from option by default. If it's set to the special value quiet the --quiet option is enabled and From: lines are left alone by default. Any other non-empty value is taken as a default --from=<value> option. The --no-from option will temporarily disable use of the config value.

If additional non-tg options are passed through to git diff-tree (other than --binary which is fully supported) the resulting tg patch output may not be appliable.

tg mail

tg [...] mail [-s <send-email-args>] [-r <reference-msgid>] [-i | -w] [<name>]

Options:

  -i                  use TopGit metadata from index instead of HEAD branch

  -w                  use metadata from working directory instead of branch

Send a patch from the current or specified topic branch as email(s).

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 the documentation for that 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. The -r parameter with a msgid can be used to generate in-reply-to and reference headers to an earlier mail.

WARNING: be careful when using this command. It easily sends out several mails. You might want to run:

git config sendemail.confirm always

to let git send-email ask for confirmation before sending any mail.

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

tg [...] remote [--populate] [<remote>]

Register the given remote as TopGit-controlled. This will create the namespace for the remote branch bases and teach git fetch to operate on them. However, from TopGit 0.8 onwards you need to use tg push, or git push --mirror, for pushing TopGit-controlled branches.

tg remote takes an optional remote name argument, and an optional --populate switch. Use --populate for your origin-style remotes: 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 look at branches of this remote for updates by default.

Using --populate with a remote name causes the topgit.remote git configuration variable to be set to the given remote name.

tg summary

tg [...] summary [<option>...] [--all | <branch>...]

tg [...] summary [--terse | --list] [<option>...] [--all | <branch>...]

tg [...] summary --rdeps[-full] [<option>...] [--all | <branch>...]

tg [...] summary --heads[-independent] [<option>...] [--all | <branch>...]

tg [...] summary --deps [<option>...] [--all | <branch>...]

tg [...] summary --deps-only [<option>...] [--all | <branch>...]

tg [...] summary --sort [<option>...] [--all | <branch>...]

tg [...] summary --graphviz [<option>...] [--all | <branch>...]

Options:

  --terse / --list    list TopGit branches (aka '-t' / '-l')

  --rdeps[-once]      show branch dependencies as multi-indented list

  --rdeps-full        like '--rdeps' but do not collapse repeated items

  --rdeps --heads     use '--rdeps' and $('--heads of <branch>...)

  --[topgit]-heads    list only independent TopGit branch heads

  --heads-independent list only merge-base --independent heads

  --deps              list all .topdeps branch dependencies

  --deps-only         list sorted unique .topdeps branches + dependencies

  --sort              feed output of '--deps' through 'tsort'

  --graphviz          generate dependency graph description in DOT format

  --verbose / -v      include subjects with '-l' (twice shows annihilated)

  --exclude <branch>  exclude <branch> during operation (may be repeated)

  --tgish-only        exclude non-TopGit branches (aka '--tgish')

  --with-deps         include dependencies of given <branch>... (default)

  --without-deps      do not include dependencies of given <branch>...

  --with-related      use '--with-deps' and $('--heads' of <branch>...)

  --without-related   do not use '--with-related' processing

  --heads-only        use '--without-deps' and $('--heads' of <branch>...)

  -i                  use TopGit metadata from index instead of HEAD branch

  -w                  use metadata from working directory instead of branch

Show overview of all TopGit-tracked topic branches and their up-to-date status. With a branch name limit output to that branch. Using --deps-only or --rdeps changes the default from all branches to just the current HEAD branch but using --all as the branch name will show results for all branches instead of HEAD.

>

marks the current topic branch

0

indicates that it introduces no changes of its own

l/r

indicates respectively whether it is local-only or has a remote mate

L/R

indicates respectively if it is ahead or out-of-date with respect to its remote mate

D

indicates that it is out-of-date with respect to its dependencies

!

indicates that it has missing dependencies [even if they are recursive ones]

B

indicates that it is out-of-date with respect to its base

*

indicates it is ahead of (and needs to be merged into) at least one of its dependents – only computed when showing all branches or using the (possibly implied) --with-deps option.

This can take a longish time to accurately determine all the relevant information about each branch; you can pass -t (or -l or --list) to get just a terse list of topic branch names quickly. Also adding --verbose (or -v) includes the subjects too. Adding a second --verbose includes annihilated branches as well.

Passing --heads shows independent topic branch names and when combined with --rdeps behaves as though --rdeps were run with the output of --heads.

The --heads-independent option works just like --heads except that it computes the heads using git merge-base --independent rather than examining the TopGit .topdeps relationships. If the TopGit branches are all up-to-date (as shown in tg summary) then both --heads and --heads-independent should compute the same list of heads (unless some overlapping TopGit branches have been manually created). If not all the TopGit branches are up-to-date then the --heads-independent results may have extra items in it, but occasionally that's what's needed; usually it's the wrong answer. (Note that --topgit-heads is accepted as an alias for --heads as well.)

Using --heads-only behaves as though the output of --heads was passed as the list of branches along with --without-deps.

Alternatively, you can pass --graphviz to get a dot-suitable output for drawing a dependency graph between the topic branches.

You can also use the --sort option to sort the branches using a topological sort. This is especially useful if each TopGit-tracked topic branch depends on a single parent branch, since it will then print the branches in the dependency order. In more complex scenarios, a text graph view would be much more useful, but that has not yet been implemented.

The --deps option outputs dependency information between branches in a machine-readable format. Feed this to tsort to get the output from --sort.

The --deps-only option outputs a sorted list of the unique branch names given on the command line plus all of their recursive dependencies (subject to --exclude of course). When --deps-only is given the default is to just display information for HEAD, but that can be changed by using --all as the branch name. Each branch name will appear only once in the output no matter how many times it's visited while tracing the dependency graph or how many branch names are given on the command line to process.

The --rdeps option outputs dependency information in an indented text format that clearly shows all the dependencies and their relationships to one another. When --rdeps is given the default is to just display information for HEAD, but that can be changed by using --all as the branch name or by adding the --heads option. Note that tg summary --rdeps --heads can be particularly helpful in seeing all the TopGit-controlled branches in the repository and their relationships to one another.

Note that --rdeps has two flavors. The first (and default) is --rdeps-once which only shows the dependencies of a branch when it's first visited. For example, if D depends on several other branches perhaps recursively and both branch A and B depend on D, then whichever of A or B is shown first will show the entire dependency chain for D underneath it and the other one will just show a line for D itself with a "^" appended to indicate that the rest of the deps for D can be found above. This can make the output a bit more compact without actually losing any information which is why it's the default. However, using the --rdeps-full variant will repeat the full dependency chain every time it's encountered.

Adding --with-deps replaces the given list of branches (which will default to HEAD if none are given) with the result of running tg summary --deps-only --tgish on the list of branches. This can be helpful in limiting tg summary output to only the list of given branches and their dependencies when many TopGit-controlled branches are present in the repository. Use --without-deps to switch back to the old behavior.

The --with-related option extends (and therefore implies) --with-deps. First the list of branches (which will default to HEAD if none are given) is replaced with the result of running tg summary --heads (aka --topgit-heads) and the result is then processed as though it had been specified using --with-deps.

When it would be allowed, --with-deps is now the default. But, if in addition, exactly one branch is specified (either explicitly or implicitly) and it's spelled exactly as HEAD or @ then the default --with-deps will be promoted to a default --with-related instead. Since duplicate branches are removed before processing, explicitly listing @ twice provides an easy way to defeat this automatic promotion and ask for --with-deps on the HEAD symbolic ref with minimal typing when --with-related isn't really wanted and typing the full --with-deps option is too hard.

With --exclude branch, branch can be excluded from the output meaning it will be skipped and its name will be omitted from any dependency output. The --exclude option may be repeated to omit more than one branch from the output. Limiting the output to a single branch that has been excluded will result in no output at all.

The --tgish-only option behaves as though any non-TopGit-controlled dependencies encountered during processing had been listed after an --exclude option.

Note that the branch name can be specified as HEAD or @ as a shortcut for the TopGit-controlled branch that HEAD is a symbolic ref to. The tg summary @ and tg summary @ @ commands can be quite useful.

tg contains

tg [...] contains [-v] [-r] [--ann] [--no-strict] [--] <committish>

Search all TopGit-controlled branches (and optionally their remotes) to find which TopGit-controlled branch contains the specified commit.

This is more than just basic branch containment as provided for by the git branch --contains command. While the shown branch name(s) will, indeed, be one (or more) of those output by the git branch --contains command, the result(s) will exclude any TopGit-controlled branches from the result(s) that have one (or more) of their TopGit dependencies (either direct or indirect) appearing in the git branch --contains output.

Normally the result will be only the one, single TopGit-controlled branch for which the specified committish appears in the tg log output for that branch (unless the committish lies outside the TopGit-controlled portion of the DAG and --no-strict was used).

Unless --annihilated-okay (or --ann or --annihilated) is used then annihilated branches will be immediately removed from the git branch --contains output before doing anything else. This means a committish that was originally located in a now-annihilated branch will show up in whatever branch picked up the annihilated branch's changes (if there is one). This is usually the correct answer, but occasionally it's not; hence this option. If this option is used together with --verbose then annihilated branches will be shown as "[:annihilated:]".

In other words, if a tg patch is generated for the found branch (assuming one was found and a subsequent commit in the same branch didn't then revert or otherwise back out the change), then that patch will include the changes introduced by the specified committish (unless, of course, that committish is outside the TopGit-controlled portion of the DAG and --no-strict was given).

This can be very helpful when, for example, a bug is discovered and then after using git bisect (or some other tool) to find the offending commit it's time to commit the fix. But because the TopGit merging history can be quite complicated and maybe the one doing the fix wasn't the bug's author (or the author's memory is just going), it can sometimes be rather tedious to figure out which TopGit branch the fix belongs in. The tg contains command can quickly tell you the answer to that question.

With the --remotes (or -r) option a TopGit-controlled remote branch name may be reported as the result but only if there is no non-remote branch containing the committish (this can only happen if at least one of the TopGit-controlled local branches are not yet up-to-date with their remotes).

With the --verbose option show which TopGit DAG head(s) (one or more of the TopGit-controlled branch names output by tg summary --heads) have the result as a dependency (either direct or indirect). Using this option will noticeably increase running time.

With the default --strict option, results for which the base of the TopGit-controlled branch contains the committish will be suppressed. For example, if the committish was deep-down in the master branch history somewhere far outside of the TopGit-controlled portion of the DAG, with --no-strict, whatever TopGit-controlled branch(es) first picked up history containing that committish will be shown. While this is a useful result it's usually not the desired result which is why it's not the default.

To summarize, even with --remotes, remote results are only shown if there are no non-remote results. Without --no-strict (because --strict is the default) results outside the TopGit-controlled portion of the DAG are never shown and even with --no-strict they will only be shown if there are no --strict results. Finally, the TopGit head info shown with --verbose only ever appears for local (i.e. not a remote branch) results. Annihilated branches are never considered possible matches without --annihilated-okay.

tg checkout

tg [...] checkout [<opt>...] [-b <branch>] (next | prev) [<steps>]

tg [...] checkout [<opt>...] (next | prev) -a

tg [...] checkout [<opt>...] [goto] [--] <pattern> | --series[=<head>]

Options:

  --iow               pass '--ignore-other-worktrees' to git >= v2.5.0

  --force / -f        pass '--force' option to git

  --merge / -m        pass '--merge' option to git

  --quiet / -q        pass '--quiet' option to git

  --branch <branch>   start at branch <branch> instead of HEAD

  -b <branch>         alias for --branch <branch>

  --all / -a          step as many times as possible

Switch to a topic branch. You can use git checkout <branch> to get the same effect, but this command helps you navigate the dependency graph, or allows you to match the topic branch name using a regular expression, so it can be more convenient.

The --branch (or -b or --branch=<name>) option changes the default starting point from HEAD to the specified branch.

For the "next" and "previous" commands, the <steps> value may be --all (or -a) to take "As many steps As possible" or "step ALL the way" or "ALL steps at once" (or make something better up yourself).

The following subcommands are available:

tg checkout next [<steps>]

Check out a branch that directly depends on your current branch. Move <steps> (default 1) step(s) in the "next" direction (AKA n).

tg checkout prev [<steps>]

Check out a branch that this branch directly depends on. Move <steps> (default 1) step(s) in the "previous" direction (AKA p or previous).

tg checkout [goto] [--] <pattern>

Check out a topic branch that matches <pattern>. <pattern> is used as a grep ERE pattern to filter all the topic branches. Both goto and -- may be omitted provided <pattern> is not -a, --all, -h, --help, goto, --, n, next, push, child, p, prev, previous, pop, parent, +, - or ...

tg checkout [goto] [--] --series[=<head>]

Check out a topic branch that belongs to the current (or <head>) patch series. A list with descriptions (tg info --series) will be shown to choose from if more than one.

tg checkout + [<steps>]

An alias for next.

tg checkout push [<steps>]

An alias for next.

tg checkout child [<steps>]

Deprecated alias for next.

tg checkout

Semi-deprecated alias for next.

tg checkout - [<steps>]

An alias for prev.

tg checkout pop [<steps>]

An alias for prev.

tg checkout parent [<steps>]

Deprecated alias for prev.

tg checkout .. [<steps>]

Semi-deprecated alias for prev.

If any of the above commands can find more than one possible branch to switch to, you will be presented with the matches and asked to select one of them.

Note that unless overridden by an explicit alias (see ALIASES), tg goto is an implicit alias for tg checkout goto.

If the --ignore-other-worktrees (or --iow) option is given and the current Git version is at least 2.5.0 then the full --ignore-other-worktrees option will be passed along to the git checkout command when it's run (otherwise the option will be silently ignored and not passed to Git as it would cause an error).

The --force (or -f) option, when given, gets passed through to the git checkout command.

The --merge (or -m) option, when given, gets passed through to the git checkout command.

The --quiet (or -q) option, when given, gets passed through to the git checkout command.

The <pattern> of tg checkout goto is optional. If you don't supply it, all the available topic branches are listed and you can select one of them.

Normally, the next and prev commands move one step in the dependency graph of the topic branches. The -a option causes them (and their aliases) to move as far as possible. That is, tg checkout next -a moves to a topic branch that depends (directly or indirectly) on the current branch and that no other branch depends on. tg checkout prev -a moves to a topic branch that the current topic branch depends on (directly or indirectly). If there is more than one possibility, you will be prompted for your selection.

See also NAVIGATION.

tg export

tg [...] export [--collapse] [--force] [<option>...] <newbranch>

tg [...] export --linearize [--force] [<option>...] <newbranch>

tg [...] export --quilt [--force] [-a | --all | -b <branch>...] [--binary] [--flatten] [--numbered] [--strip[=N]] <directory>

Options:

  -s <mode>           set subject bracketed [strings] strip mode

  --notes[=<ref>]     export .topmsg --- comment to notes ref <ref>

  --no-notes          discard .topmsg --- comment (default)

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 three possible outputs now – either a Git branch with the collapsed history, a Git branch with a linearized history, or a quilt series in new directory.

In the case where you are producing collapsed history in a new branch, you can use this collapsed structure either for providing a pull source for upstream, or for 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:

origin/master - t/foo/blue - t/foo/red - master
             `- t/bar/good <,----------'
             `- t/baz      ------------'

(where each of the branches may have a hefty history). Then:

master$ tg export for-linus

will create this commit structure on the branch for-linus:

origin/master - t/foo/blue -. merge - t/foo/red -.. merge - master
             `- t/bar/good <,-------------------'/
             `- t/baz      ---------------------'

In this mode, tg export works on the current topic branch, and can be called either without an option (in that case, --collapse is assumed), or with the --collapse option, and with one mandatory argument: the name of the branch where the exported result will be stored.

Both the --collapse and --linearize modes also accept a -s <mode> option to specify subject handling behavior for the freshly created commits. There are five possible modes:

keep:	Like git mailinfo -k
mailinfo:	Like git mailinfo
patch:	Remove first [PATCH*] if any
topgit:	Remove first [PATCH*], [BASE], [ROOT] or [STAGE]
trim:	Trim runs of spaces/tabs to a single space

The topgit (aka tg) mode is the default (quelle surprise) and like the patch mode will only strip the first square brackets tag (if there is one) provided it's a TopGit-known tag (the patch variation will only strip a "[PATCH*]" tag but still just the first one). Note that TopGit does understand "[RELEASE]" in topgit mode. With trim (aka ws) internal runs of spaces/tabs are converted to a single space, but no square brackets tags are removed. The ws mode should generally be preferred instead of using keep mode. All modes always remove leading/trailing spaces and tabs and if the topgit.subjectPrefix value (see tg create) has been set both the topgit and patch modes will match tags with that prefix too.

Setting the config variable topgit.subjectMode to one of the mode values shown above will change the default to that mode.

Both the --collapse and --linearize modes also accept a --notes[=<ref>] option to export the portion of the .topmsg file following a --- separator line to the specified notes ref. If <ref> is omitted then refs/notes/commits will be used. If <ref> does not start with refs/notes/ then refs/notes/ will be prepended unless it starts with notes/ in which case only refs/ will be prepended.

Setting the config variable topgit.notesExport to a boolean or to a <ref> name will set the default for the --notes option (with no config or --notes[=<ref>] option the --- comment is discarded by default). To override a topgit.notesExport option and discard any --- comments, use --no-notes.

When using the linearize mode:

master$ tg export --linearize for-linus

you get a linear history respecting the dependencies of your patches in a new branch for-linus. The result should be more or less the same as using quilt mode and then reimporting it into a Git branch. (More or less because the topological order can usually be extended in more than one way into a total order, and the two methods may choose different ones.) The result might be more appropriate for merging upstream, as it contains fewer merges.

Note that you might get conflicts during linearization because the patches are reordered to get a linear history. If linearization would produce conflicts then using --quilt will also likely result in conflicts when the exported quilt series is applied. Since the --quilt mode simply runs a series of tg patch commands to generate the patches in the exported quilt series and those patches will end up being applied linearly, the same conflicts that would be produced by the --linearize option will then occur at that time.

To avoid conflicts produced by --linearize (or by applying the --quilt output), use the default --collapse mode and then use tg rebase (or git rebase -m directly) on the collapsed branch (with a suitable <upstream>) followed by git format-patch on the rebased result to produce a conflict-free patch set. A suitable upstream may be determined with the tg info --leaves command (if it outputs more than one line, linearization will be problematic).

You have enabled git rerere haven't you?

When using the quilt mode:

master$ tg export --quilt for-linus

would create the following 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

With --quilt, you can also pass the -b parameter followed by a comma-separated explicit list of branches to export, or the --all parameter (which can be shortened to -a) to export them all. The --binary option enables producing Git binary patches. These options are currently only supported with --quilt.

In --quilt mode the patches are named like the originating topgit branch. So usually they end up in subdirectories of the output directory. With the --flatten option the names are mangled so that they end up directly in the output dir (slashes are replaced with underscores). With the --strip[=N] option the first N subdirectories (all if no N is given) get stripped off. Names are always --strip'd before being --flatten'd. With the option --numbered (which implies --flatten) the patch names get a number as prefix to allow getting the order without consulting the series file, which eases sending out the patches.

Note that tg export is fully compatible with the wayback machine and when used with the --collapse or --linearize options will "push" the resulting branch back into the main repository when used in wayback mode.

TODO: Make stripping of non-essential headers configurable

TODO: --mbox option to export instead as an mbox file

TODO: support --all option in other modes of operation

TODO: For quilt exporting, export the linearized history created in a temporary branch--this would allow producing conflict-less series

tg import

tg [...] import [-d <base-branch>] [<option>...] <range>...

tg [...] import [-d <base-branch>] [<option>...] -s <name> <commit>

Options:

  -p <prefix>         prepend <prefix> to branch names (default is 't/')

  --notes[=<ref>]     import notes ref <ref> to .topmsg --- comment

  --no-notes          do not import any notes ref --- comment (default)

Import commits within the given revision range(s) into TopGit, creating one topic branch per commit. The dependencies are set up to form a linear sequence starting on your current branch -- or a branch specified by the -d parameter, if present.

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

Each "<range>" must be of the form <rev1>..<rev2> where either <rev1> or <rev2> can be omitted to mean HEAD. Additionally the shortcut <rev>^! (see git help revisions) is permitted as a "<range>" to select the single commit <rev> but only if the commit <rev> has exactly one parent. This is really just a shortcut for <rev>^..<rev> but somewhat safer since it will fail if <rev> has other than one parent.

Alternatively, you can use the -s NAME parameter to specify the name of the target branch; the command will then take one more argument describing a single commit to import which must not be a merge commit.

Use the --notes[=<ref>] option to import the git notes associated with the commit being imported to the .topmsg file – if non-empty notes are present, they will be appended to the generated .topmsg file preceded by a --- separator line. If <ref> is omitted then refs/notes/commits will be used. If <ref> does not start with refs/notes/ then refs/notes/ will be prepended unless it starts with notes/ in which case only refs/ will be prepended.

Setting the config variable topgit.notesImport to a boolean or to a <ref> name will set the default for the --notes option (with no config or --notes[=<ref>] option no --- comment is added to the generated .topmsg file by default). To override a topgit.notesImport option and not add any --- comments, use --no-notes.

tg update

tg [...] update [--[no-]stash] [--skip-missing] ([<name>...] | -a [<pattern>...])

tg [...] update --base [-F <file> | -m <msg>] [--[no-]edit] [-f] <base-branch> <ref>

tg [...] update --continue | --skip | --stop | --abort

Update the current, specified or all topic branches with respect to changes in the branches they depend 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 on what to do next in case of conflicts.

You have enabled git rerere haven't you?

Remember the default expiration time for resolved merge conflicts is only 60 days. Increase their longevity by setting the Git configuration variable gc.rerereResolved to a higher number such as 9999 like so:

git config --global gc.rerereResolved 9999

The --[no-]auto[-update] options together with the topgit.setAutoUpdate config item control whether or not TopGit will automatically temporarily set rerere.autoUpdate to true while running tg update. The default is true. Note that this does not enable Git's rerere feature, it merely makes it automatically stage any previously resolved conflicts. The rerere.enabled setting must still be separately enabled (i.e. set to true) for the rerere feature to do anything at all.

Using --auto[-update] makes tg update always temporarily set rerere.autoUpdate to true while running tg update. The --no-auto[-update] option prevents tg update from changing the rerere.autoUpdate setting, but if rerere.autoUpdate has already been enabled in a config file, tg update never disables it even with --no-auto. If topgit.setAutoUpdate is unset or set to true then tg update implicitly does --auto, otherwise it does --no-auto. An explicit command line --[no-]auto[-update] option causes the topgit.setAutoUpdate setting to be ignored.

When both rerere.enabled and rerere.autoUpdate are set to true then tg update will be able to automatically continue an update whenever git rerere resolves all the conflicts during a merge. This can be such a huge time saver. That's why the default is to have TopGit automatically set rerere.autoUpdate to true while tg update is running (but remember, unless rerere.enabled has been set to true it won't make any difference).

When -a (or --all) is specified, updates all topic branches matched by <pattern>'s (see git-for-each-ref(1) for details), or all if no <pattern> is given. Any topic branches with missing dependencies will be skipped entirely unless --skip-missing is specified.

When --skip-missing is specified, an attempt is made to update topic branches with missing dependencies by skipping only the dependencies that are missing. Caveat utilitor.

When --stash is specified (or the topgit.autostash config value is set to true), a ref stash will be automatically created just before beginning updates if any are needed. The --no-stash option may be used to disable a topgit.autostash=true setting. See the tg tag --stash option for details.

After the update, the branch which was current at the beginning of the update is returned to.

If your dependencies are not up-to-date, tg update will first recurse into them and update them.

If a remote branch update brings in dependencies on branches that are 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 ! next to them). TopGit will attempt to instantiate just the missing ones automatically for you, if possible, when tg update merges in the new dependencies from the remote.

Using the alternative --base mode, tg update will update the base of a specified [BASE] branch (which is a branch created by tg create using the --base option) to the specified committish (the second argument) and then immediately merge that into the branch itself using the specified message for the merge commit. If no message is specified on the command line, an editor will open. Unless --force is used the new value for the base must contain the old value (i.e. be a fast-forward update). This is for safety.

This mode makes updates to [BASE] branches quick and easy.

TODO: tg update -a -c to autoremove (clean) up-to-date branches

tg push

tg [...] push [--dry-run] [--force] [--no-deps] [--tgish-only] [-r <pushRemote>] [-a | --all | <branch>...]

If -a or --all was specified, pushes all non-annihilated TopGit-controlled topic branches, to a remote repository. Otherwise, pushes the specified topic branches – or the current branch, if you don't specify which. By default, the remote gets all the dependencies (both TopGit-controlled and non-TopGit-controlled) and bases pushed to it too. If --tgish-only was specified, only TopGit-controlled dependencies will be pushed, and if --no-deps was specified, no dependencies at all will be pushed.

All TopGit branches to be pushed must be up-to-date unless the --allow-outdated option is given. Branches are checked against the configured TopGit remote (topgit.remote) if it's set (as modified by the global -u and -r <remote> options).

The --dry-run, --force, --atomic, --follow-tags, --no-follow-tags, --signed[=...], -4 and -6 options are passed through directly to git push if given.

The push remote may be specified with the -r option. If no remote was specified, the configured default TopGit push remote will be used (topgit.pushRemote) or if that's unset the regular remote (topgit.remote).

Note that when pushing to a configured Git remote (i.e. it appears in the git remote output) that appears to have local tracking branches set up for the remote TopGit branches and/or TopGit bases, tg push will attempt to make sure the local tracking branches are updated to reflect the result of a successful tg push. This is the same as the normal Git behavior except that tg push will always attempt to make sure that both the local tracking branches for the remote TopGit branches and their bases are always updated together even if the configured Git remote only has a fetch refspec for one of them. If the remote branches are being tracked by the configured Git remote in a non-standard local tracking branch location, it may be necessary to issue a subsequent git fetch on that remote after a successful tg push in order for them to be updated to reflect the tg push.

Use something like this to push to an origin remote when it's set as topgit.remote while only checking for local out-of-dateness:

tg -u push -r origin <optional-branch-names-here>

tg base

tg [...] base [--short[=<n>] | --no-short] [--] [branch...]

Options:

  --short[=<n>]       display shortened hashes (default)

  --no-short          display full hashes

Prints the base commit of each of the named topic branches, or the current branch if no branches are named. Prints an error message and exits with exit code 1 if the named branch is not a TopGit branch.

tg log

tg [...] log [--compact] [<name>] [--] [<git-log-option>...]

Prints the git log of the named topgit branch – or the current branch, if you don't specify a name.

This is really just a convenient shortcut for:

git log --first-parent --no-merges $(tg base <name>)..<name>

where <name> is the name of the TopGit topic branch (or omitted for the current branch).

However, if <name> is a [BASE] branch the --no-merges option is omitted.

If --compact is used then git log-compact will be used instead of git log. The --command=<git-alias> option can be used to replace "log" with any non-whitespace-containing command alias name, --compact is just a shortcut for --command=log-compact. The git-log-compact tool may be found on its project page located at:

https://mackyle.github.io/git-log-compact

Note that the --compact or --command= option must be used before any -- or git log options to be recognized.

NOTE: if you have merged changes from a different repository, this command might not list all interesting commits.

tg tag

tg [...] tag [<option>...] <tagname> [<branch>...]

tg [...] tag [<option>...] --refs [<branch>...]

tg [...] tag [<option>...] (-g | --reflog) [<tagname>]

tg [...] tag --clear <tagname>

tg [...] tag --delete <tagname>

tg [...] tag --drop <tagname>@{n}

Options:

  --refs[-only]       show TOPGIT REFS but do not actually create a tag

  --reflog / -g       show tag reflog instead of creating a tag

  --walk-reflogs      alias for --reflog

  --clear             clear tag's reflog to @{0} instead of creating a tag

  --delete            delete the tag and its reflog instead of creating

  --drop              drop the tag's specified reflog entry (no create)

  --quiet / -q        suppress info messages (repeating suppresses more)

  --sign / -s         create a signed tag

  --force / -f        replace existing tag with same name

  -u <keyid>          sign with <keyid> (implies '--sign')

  --local-user <k>    alias for '-u <k>'

  --message <msg>     replace default tag message

  -m <msg>            (default message is "tag ... branches ...")

  --file <file>       replace default tag message

  -F <file>           with contents of <file>

  --edit              run the editor on the default tag message (default)

  --no-edit           do not run the editor on the default tag message

  --tree <treeish>    force created <tagname>^{tree} to be <treeish>

  --all               use all branches for <branch>... (default is HEAD)

  --allow-outdated    allow outdated TopGit branches to be included

  --stash             use refs/tgstash for <tagname> (implies '--all')

  --reflog-message    use reflog message for '--walk-reflogs'

  --commit-message    use commit message for '--walk-reflogs'

  --no-type           omit non-tag annotation in '--walk-reflogs' mode

  --max-count <n>     show at most <n> reflog entries in '-g' mode

  -n <n> / -<n>       alias for '--max-count <n>'

Creates a TopGit annotated/signed tag or lists the reflog of one.

A TopGit annotated tag records the current state of one or more TopGit branches and their dependencies and may be used to revert to the tagged state at any point in the future.

When reflogs are enabled (the default in a non-bare repository) and combined with the --force option a single tag name may be used as a sort of TopGit branch state stash. The special branch name --all may be used to tag the state of all current TopGit branches to facilitate this function and has the side-effect of suppressing the out-of-date check allowing out-of-date branches to be included.

As a special feature, --stash may be used as the tag name in which case --all is implied if no branch name is listed (instead of the normal default of HEAD), --force and --no-edit (use --edit to change that) are automatically activated and the tag will be saved to refs/tgstash instead of refs/tags/<tagname>. The --stash tag name may also be used with the -g/--reflog option.

The mostly undocumented option --allow-outdated will bypass the out-of-date check and is implied when --stash or --all is used.

A TopGit annotated/signed tag is simply a Git annotated/signed tag with a "TOPGIT REFS" section appended to the end of the tag message (and preceding the signature for signed tags). PEM-style begin and end lines surround one line per ref where the format of each line is full-hash SP ref-name. A line will be included for each branch given on the command line and each ref they depend on either directly or indirectly.

Note that when specifying branch names, if a given name is ambiguous but prefixing the branch name with refs/heads/ successfully disambiguates it, then that will be the interpretation used.

If more than one TopGit branch is given on the command line, a new commit will be created that has an empty tree and all of the given TopGit branches as parents and that commit will be tagged. If a single TopGit branch is given, then it will be tagged. If the --tree option is used then it will be used instead of an empty tree (a new commit will be created if necessary to guarantee the specified tree is what's in the commit the newly created tag refers to). The argument to the --tree option may be any valid treeish.

If exactly one of the branches to be tagged is prefixed with a tilde (~) it will be made the first parent of a consolidation commit if it is not already the sole commit needing to be tagged. If --tree is NOT used, its tree will also be used instead of the empty tree for any new consolidation commit if one is created. Note that if --tree is given explicitly its tree is always used but that does not in any way affect the choice of first parent. Beware that the ~ may need to be quoted to prevent the shell from misinterpreting it into something else.

All the options for creating a tag serve the same purpose as their Git equivalents except for two. The --refs option suppresses tag creation entirely and emits the "TOPGIT REFS" section that would have been included with the tag. If the --no-edit option is given and no message is supplied (via the -m or -F option) then the default message created by TopGit will be used without running the editor.

With -g or --reflog show the reflog for a tag. With the --reflog-message option the message from the reflog is shown. With the --commit-message option the first line of the tag's message (if the object is a tag) or the commit message (if the object is a commit) falling back to the reflog message for tree and blob objects is shown. The default is --reflog-message unless the --stash (refs/tgstash) is being shown in which case the default is then --commit-message. Just add either option explicitly to override the default.

When showing reflogs, non-tag entries are annotated with their type unless --no-type is given. Custom colors can be set with these git config options:

color.tgtag:	enable/disable color, default is color.ui
color.tgtag.commit:
	hash color, dflt color.diff.commit/yellow
color.tgtag.date:
	date line color, default is bold blue
color.tgtag.meta:
	object type "color", default is bold
color.tgtag.time:
	time info color, default is green

TopGit tags are created with a reflog if core.logallrefupdates is enabled (the default for non-bare repositories). Unfortunately Git is incapable of showing an annotated/signed tag's reflog (using either git log -g or git reflog show). Git can, however, show reflogs for lightweight tags just fine but that's not helpful here. Use tg tag with the -g or --reflog option to see the reflog for an actual tag object. This also works on non-TopGit annotated/signed tags as well provided they have a reflog.

Note that the time and date shown for reflog entries by tg tag -g is the actual time and date recorded in that reflog entry itself which usually is the time and date that entry was added to the reflog, not the time and date of the commit it refers to. Git itself will only ever show the time and date recorded in a reflog entry when given just the right arguments to git log, but then the reflog entry's time and date are always shown in place of its index number.

By contrast, tg tag -g always shows the reflog entry's time and date together with its reflog entry index number.

The number of entries shown may be limited with the -n option. If the tagname is omitted then --stash is assumed.

The --delete option is a convenience option that runs the git update-ref --no-deref -d command on the specified tag removing it and its reflog (if it has one). Note that HEAD cannot be removed.

The --clear option clears all but the most recent (the @{0}) reflog entry from the reflog for the specified tag. It's equivalent to dropping all the higher numbered reflog entries.

The --drop option drops the specified reflog entry and requires the given tagname to have an @{n} suffix where n is the reflog entry number to be dropped. This is really just a convenience option that runs the appropriate git reflog delete command. Note that even dropping the ...@{0} entry when it's the last entry of a non-symbolic ref will NOT delete the ref itself (unless the ref was already somehow set to an invalid object hash); but dropping @{0} of a non-symbolic ref may have the side effect of removing some stale reflog entries that were present in the reflog.

Note that when combined with tg revert, a tag created by tg tag can be used to transfer TopGit branches. Simply create the tag, push it somewhere and then have the recipient run tg revert to recreate the TopGit branches. This may be helpful in situations where it's not feasible to push all the refs corresponding to the TopGit-controlled branches and their top-bases.

tg rebase

tg [...] rebase (-m | --merge) [<git-rebase-arg>...]

Provides a git rebase rerere auto continue function. It may be used as a drop-in replacement front-end for git rebase -m that automatically continues the rebase when git rerere information is sufficient to resolve all conflicts.

You have enabled git rerere haven't you?

If the -m or --merge option is not present then tg rebase will complain and not do anything.

When git rerere is enabled, previously resolved conflicts are remembered and can be automatically staged (see rerere.autoUpdate).

However, even with auto staging, git rebase still stops and requires an explicit git rebase --continue to keep going.

In the case where git rebase -m is being used to flatten history (such as after a tg export --collapse prior to a git format-patch), there's a good chance all conflicts have already been resolved during normal merge maintenance operations so there's no reason git rebase could not automatically continue, but there's no option to make it do so.

The tg rebase command provides a git rebase --auto-continue function.

All the same rebase options can be used (they are simply passed through to Git unchanged). However, the rerere.autoUpdate option is automatically temporarily enabled while running git rebase and should git rebase stop, asking one to resolve and continue, but all conflicts have already been resolved and staged using rerere information, then git rebase --continue will be automatically run.

tg revert

tg [...] revert (-f | -i | -n) [<opt>...] (<tagname> | --stash) [<ref>...]

tg [...] revert [<opt>...] (<tagname> | --stash) [(--[topgit-]heads] | <ref>...)]

Options:

  --quiet / -q        suppress non-dry-run ref change messages

  --force / -f        force revert operation to make changes

  --dry-run / -n      show '-f' changes but don't actually make them

  --interactive / -i  edit revert instruction sheet before proceeding

  --list / -l         list mode (default if no -f, -n or -i present)

  --short[=<n>]       display shortened hashes (default unless --hash)

  --no-short          display full hashes (default for --hash-only)

  --hash-only         show only hashes in list mode (aka '--hash')

  --no-stash          skip preliminary stash before making changes

  --exclude <ref>     exclude <ref> during operation (may be repeated)

  --tgish-only        exclude non-TopGit branches (aka '--tgish')

  --no-deps           do not include dependencies in revert mode

  --deps              include dependencies in list mode

  --rdeps             list relationships like 'tg summary --rdeps'

  --stash             specifies a <tagname> of refs/tgstash

  --heads             list only merge-base --independent heads

  --heads-independent alternate spelling of '--heads'

  --topgit-heads      list only independent TopGit branch heads

Provides the ability to revert one or more TopGit branches and their dependencies to a previous state contained within a tag created using the tg tag command. In addition to the actual revert mode operation a list mode operation is also provided to examine a tag's ref contents.

The default mode (-l or --list) shows the state of one or more of the refs/branches stored in the tag data. When no refs are given on the command line, all refs in the tag data are shown. With the special ref name --heads then the indepedent heads contained in the tag data are shown. The --deps option shows the specified refs and all of their dependencies in a single list with no duplicates. The --rdeps option shows a display similar to tg summary --rdeps for each ref or all TopGit heads if no ref is given on the command line. The standard --no-short, --short=n etc. options may be used to override the default --short output. With --hash (or --hash-only) show only the hash in --list mode in which case the default is --no-short. The --hash option can be used much like the git rev-parse --verify command to extract a specific hash value out of a TopGit tag.

Note that unlike tg summary, here --heads actually does mean the git merge-base --independent heads of the stored refs from the tag data. To see only the independent TopGit topic branch heads stored in the tag data use the --topgit-heads option instead. The default for the --rdeps option is --topgit-heads but --heads can be given explicitly to change that. (Note that --heads-independent is accepted as an alias for --heads as well.)

The revert mode has three submodes, dry-run mode (-n or --dry-run), force mode (-f or --force) and interactive mode (-i or --interactive). If --dry-run (or -n) is given no ref updates will actually be performed but what would have been updated is shown instead. If --interactive (or -i) is given then the editor is invoked on an instruction sheet allowing manual selection of the refs to be updated before proceeding. Since revert is potentially a destructive operation, at least one of the submodes must be specified explicitly. If no refs are listed on the command line then all refs in the tag data are reverted. Otherwise the listed refs and all of their dependencies (unless --no-deps is given) are reverted. Unless --no-stash is given a new stash will be created using tg tag --stash (except, of course, in dry-run mode) just before actually performing the updates to facilitate recovery from accidents.

Both modes accept fully-qualified (i.e. starts with refs/) ref names as well as unqualified names (which will be assumed to be located under refs/heads/). In revert mode a tgish ref will always have both its refs/heads/ and refs/top-bases/ values included no matter how it's listed unless --no-deps is given and the ref is fully qualified (i.e. starts with refs/) or one or the other of its values was removed from the instruction sheet in interactive mode. In list mode a tgish ref will always have both its refs/heads/ and refs/top-bases/ values included only when using the --deps or --rdeps options.

The --tgish-only option excludes non-tgish refs (i.e. refs that do not have a refs/heads/<name>, refs/top-bases/<name> pair).

The --exclude option (which can be repeated) excludes specific refs. If the name given to --exclude is not fully-qualified (i.e. starts with refs/) then it will exclude both members of a tgish ref pair.

The --quiet (or -q) option may be used in revert mode to suppress non-dry-run ref change status messages.

The special tag name --stash (as well as with @{n} suffixes) can be used to refer to refs/tgstash.

The tg revert command supports tags of tags that contains TopGit refs. So, for example, if you do this:

tg tag newtag --all
git tag -f -a -m "tag the tag" newtag newtag

Then newtag will be a tag of a tag containing a TOPGIT REFS section. tg revert knows how to dereference the outermost tag to get to the next (and the next etc.) tag to find the TOPGIT REFS section so after the above sequence, the tag newtag can still be used successfully with tg revert.

NOTE: If HEAD points to a ref that is updated by a revert operation then NO WARNING whatsoever will be issued, but the index and working tree will always be left completely untouched (and the reflog for the pointed-to ref can always be used to find the previous value).

tg shell

tg [...] -w [:]<tgtag> shell [--directory=<dirpath>] [-q] [--] [<arg>...]

Enter extended wayback machine mode.

The global -w <tgtag> option must be specified (but as a special case for the shell command a <tgtag> destination of : may be used to get a shell with no wayback ref changes).

The "<tgtag>" value must be the name of a tag created by (or known to) tg tag. However, it may also have a : prefixed to it to indicate that it should prune (making it into a "pruning wayback tag"). Use of a "pruning wayback tag" results in a repository that contains exclusively those refs listed in the specified tag. Otherwise the wayback repository will just revert those refs while keeping the others untouched (the default behavior).

The wayback machine activates as normal for the specified destination but then a new ${SHELL:-/bin/sh} is spawned in a temporary non-bare repository directory that shares all the same objects from the repository but has its own copy of the ref namespace where the refs specified in the wayback destination have all been changed to have their wayback values.

If any arguments are given a POSIX shell will be spawned instead concatenating all the arguments together with a space and passing them to it via a -c option. If -q (or --quote) is given then each argument will first be separately "quoted" to protect it from the shell allowing something like this:

tg -w <tgtag> shell -q git for-each-ref --format="%(refname)"

to work without needing to manually add the extra level of quoting that would otherwise be required due to the parentheses.

Most of the repository configuration will be inherited, but some will be overridden for safety and for convenience. All "gc" activity within the wayback repository will be suppressed to avoid accidents (i.e. no auto gc will run and "gc" commands will complain and not run).

Override and/or bypass this safety protection at your own peril! Especially do not run the git prune plumbing command in the wayback repository! If you do so (or bypass any of the other safeties) be prepared for corruption and loss of data in the repository. Just don't do that in the first place!

Using git wayback-tag will show the tag used to enter the wayback machine. Using git wayback-updates will show ref changes that have occurred since the wayback tag was created (it will not show refs that have since been created unless a pruning wayback tag was used). Finally, git wayback-repository will show the home repository but so will git remote -v in the output displayed for the wayback remote.

The special wayback remote refers to the original repository and can be used to push ref changes back to it. Note, however, that all default push refspecs are disabled for safety and an explicit refspec will need to be used to do so.

Unlike the normal wayback machine mode, HEAD will be detached to a new commit with an empty tree that contains the message and author from the wayback tag used. This prevents ugly status displays while avoiding the need to checkout any files into the temporary working tree. The parent of this commit will, however, be set to the wayback tag's commit making it easy to access if desired.

Also unlike the normal wayback machine mode, there are no limitations on what can be done in the temporary repository. And since it will be non-bare and writable, commands that may not have been allowed in the original repository will work too.

When the shell spawned by this command exits, the temporary wayback repository and all newly created objects and ref changes made in it, if any, will be lost. If work has been done in it that needs to be saved, it must be pushed somewhere (even if only back to the original repository using the special wayback remote).

Lastly there's the --directory option. If the --directory option is used the temporary "wayback repository" will be created at the specified location (which must either not exist or must be an empty directory – no force option available this time as too many things could easily go wrong in that case). If the --directory option is used then the "wayback repository" will persist after tg shell completes allowing it to continue to be used! Be warned though, all the same warnings that apply to git clone --shared apply to such a repository. If it's created using a tgstash tag those warnings are especially salient. Use a single argument of either : (to just create with no output) or pwd (to show the full absolute path to the new "wayback repository") when using the --directory option if the sole purpose is just to create the wayback repository for use. Note that the --directory option must be listed as the first option after the shell command name if used.

tg prev

tg [...] prev [-v] [-i | -w] [-a | -n <steps>] [<name>]

Output the "previous" branch(es) in the patch series containing the current or named branch. The "previous" branch(es) being one step away by default.

Options:

-i	show dependencies based on index instead of branch
-w	show dependencies based on working tree instead of branch
-n <steps>	take <steps> "previous" steps (default 1)
--all	take as many "previous" steps as possible (aka -a)
--verbose	show containing series name(s) (aka -v)

The -n option may also be given as --count or --count=<n>.

To list all dependencies of a branch see the --deps option of the tg info command.

See also NAVIGATION for full details on "previous" steps.

tg next

tg [...] next [-v] [-i | -w] [-a | -n <steps>] [<name>]

Output the "next" branch(es) in the patch series containing the current or named branch. The "next" branch(es) being one step away by default.

Options:

-i	show dependencies based on index instead of branch
-w	show dependencies based on working tree instead of branch
-n <steps>	take <steps> "next" steps (default 1)
--all	take as many "next" steps as possible (aka -a)
--verbose	show containing series name(s) (aka -v)

The -n option may also be given as --count or --count=<n>.

To list all dependents of a branch see the --dependents option of the tg info command.

See also NAVIGATION for full details on "next" steps.

tg migrate-bases

tg [...] migrate-bases (--dry-run | --force) [--no-remotes | --remotes-only]

Transition top-bases from old location to new location.

Beginning with TopGit release 0.19.4, TopGit has the ability to store the top-bases refs in either the old refs/top-bases/... location or the new refs/heads/{top-bases}/... location. Starting with TopGit release 0.20.0, the default is the new location.

By storing the top-bases under heads, Git is less likely to complain when manipulating them, hosting providers are more likely to provide access to them and Git prevents them from pointing at anything other than a commit object. All in all a win for everyone.

TopGit attempts to automatically detect whether the new or old location is being used for the top-bases and just do the right thing. However, by explicitly setting the config value topgit.top-bases to either refs for the old location or heads for the new location the auto-detection can be bypassed. If no top-bases refs are present in the repository the default prior to TopGit release 0.20.0 is to use the old location but starting with TopGit release 0.20.0 the default is to use the new location.

The tg migrate-bases command may be used to migrate top-bases refs from the old location to the new location (or, by using the undocumented --reverse option, vice versa).

With few exceptions (tg create -r and tg revert), all top-bases refs (both local and remote refs) are expected to be stored in the same location (either new or old). A repository's current location for storing top-bases refs may be shown with the tg --top-bases command.

TODO: tg rename

The Update Process

When a branch is "updated" using the tg update command the following steps are taken:

1. The branch and all of its dependencies (and theirs recursively) are checked to see which ones are out-of-date. See glossary.
2. Each of the branch's direct dependencies (i.e. they are listed in the branch's .topdeps file) which is out of date is updated before proceeding (yup, this is a recursive process). If the branch has a corresponding remote branch and that remote branch has removed one or more direct dependencies, then those remote-removed dependencies are automatically skipped at this stage even though the remote branch's .topdeps file will not actually be merged into the local branch until step (5).
3. Each of the branch's direct dependencies (i.e. they are listed in the branch's .topdeps file) that was updated in the previous step is now merged into the branch's corresponding base. If a remote is involved, and the branch's corresponding base does NOT contain the remote branch's corresponding base that remote base is also merged into the branch's base at this time as well (it will be the first item merged into the branch's base). As with the previous step, any remote-removed dependencies, if any, are automatically skipped at this stage.
4. If the branch has a corresponding remote branch and the branch does not already contain it, the branch's base (which was possibly already updated in step (3) to contain the remote branch's base but not the remote branch itself) is merged into the remote branch on a detached HEAD. Yup, this step can be a bit confusing and no, the updated base from step (3) has not yet been merged into the branch itself yet either. If there is no remote branch this step does not apply. Using a detached HEAD allows the contents of the base to be merged into the remote branch without actually perturbing the base's or remote branch's refs.
5. If there is a remote branch present then use the result of step (4) otherwise use the branch's base and merge that into the branch itself.

That's it! Simple, right? ;)

Unless the auto stash option has been disabled (see no undo, tg update and tg tag), a copy of all the old refs values will be stashed away immediately after step (1) before starting step (2), but only if anything is actually found to be out-of-date.

Merge Strategies

The tg update command regularly performs merges while executing an update operation. In order to speed things up, it attempts to do in-index merges where possible. It accomplishes this by using a separate, temporary index file and the git read-tree -m --aggressive command possibly assisted by the git merge-index and git merge-file commands. This combination may be repeated more than once to perform an octopus in-index merge. If this fails, the files are checked out and a normal git merge three-way merge is performed (possibly multiple times). If the normal git merge fails then user intervention is required to resolve the merge conflict(s) and continue.

Since the tg annihilate, tg create and tg depend add commands may end up running the tg update machinery behind the scenes to complete their operation they may also result in any of these merge strategies being used.

In addition to the normal Git merge strategies (if the in-index merging fails), there are four possible TopGit merge strategies that may be shown. Since they all involve use of the git read-tree -m --aggressive command they are all variations of a "trivial aggressive" merge. The "trivial" part because all of the merges done by git read-tree -m are described as "trivial" and the "aggressive" part because the --aggressive option is always used.

1. "trivial aggressive"

   Only two heads were involved and all merging was completed by the git read-tree -m --aggressive command.

2. "trivial aggressive automatic"

   Only two heads were involved but after the git read-tree -m --aggressive command completed there were still unresolved items and git merge-index had to be run (using the tg index-merge-one-file driver) which ultimately ran git merge-file at least once to perform a simple automatic three-way merge. Hence the "automatic" description and the "Auto-merging ..." output line(s).

3. "trivial aggressive octopus"

   This is the same as a "trivial aggressive" merge except that more than two heads were involved and after merging the first two heads, the git read-tree -m --aggressive step was repeated again on the result for each additional head. All merging was completed via multiple git read-tree -m --aggressive commands only. This beast is relatively rare in the wild.

4. "trivial aggressive automatic octopus"

   This is very similar to the "trivial aggressive octopus" except that at least one of the git read-tree -m --aggressive commands left unresolved items that were handled the same way as the "trivial aggressive automatic" strategy. This species is commonly seen in the wild.