git-integration(1)

NAME

git-integration - Manage integration branches in Git

SYNOPSIS

git integration --create <name> [<base>]
git integration [<action>…] [<branch>]
git integration (--continue | --abort)

DESCRIPTION

Use git integration to manage a branch which is the result of merging several in-progress topic branches onto a base branch.

Say you are developing several new features on the branches feature-a, feature-b and feature-c, while ongoing development is also happening on the master branch. Using git integration you can view the result of merging all of the feature branches into master and keep that branch updated as all of these branches change.

So you start with the following:

o---o master
    |\
    | o---o feature-a
     \
      o---o feature-b

when you create an integration branch including feature-a and feature-b:

git integration --create integration master
git integration --edit --rebuild

edit the instruction sheet to look like:

base master
merge feature-a
merge feature-b

the result will be:

o---o master
    |\
    | o---o feature-a
    |\     \
    | ------o---o integration
     \         /
      o---o---- feature-b

should further development then happen on master, rebuilding the integration branch:

git integration --rebuild integration

will give the following result:

o---o---o---o master
    |        \
    |       --o---o integration
    |\     /     /
    | o---o     /  feature-a
     \         /
      o---o---- feature-b

OPTIONS

--create: Create a new integration branch. If --edit is also specified then the instruction sheet will be opened for editing. If --rebuild is also specified then the branch will be built.

The name of the integration branch must be specified. If a second positional argument is specified then it is used as the base branch, otherwise “master” will be used.
--edit: Edit the instruction sheet for an integration branch.

If no branch name is specified then the current branch must be an existing integration branch.
--rebuild
--no-rebuild: Rebuild the integration branch. The --no-rebuild form exists to suppress automatic rebuilding if the integration.autorebuild configuration variable is set.

If no branch name is specified then the current branch must be an existing integration branch.
--cat: Print the instruction sheet for the integration branch. If this is combined with options which modify the instruction sheet, then those operations will be performed before it is printed.
--status: Prints the status of the integration branch. See the STATUS FORMAT section below.
--add=<branch>: Appends a line merge <branch> to the instruction list, causing that branch to be included in the integration branch when it is next rebuilt. This option may be specified multiple times to add multiple branches.
--continue: Restart the building process after having resolved a merge conflict.
--abort: Abort the rebuild operation and reset HEAD to the original branch.
--autocontinue
--no-autocontinue: Continues automatically if the rerere mechanism manages to resolve all conflicts during a merge.
--prefix=<prefix>: Prepend the specified string to each reference in the instruction sheet while building the integration branch. For example, if you have pulled somebody else’s instruction sheet and it references branches that you have fetched into the refs/remotes/origin/ namespace, you can use --prefix=origin/ to avoid needing to re-write the instruction sheet or import all of the refs into your local refs/heads/ namespace.

The prefix is treated as a simple string, so you probably want to include the trailing “/” if you are moving refs to a different namespace.
--version: Prints the version of git-integration in use.

If --continue or --abort are specified then no other options may be given. Otherwise at least one of --create, --add, --edit, --cat or --rebuild must be specified. If more than one is specified then they will be performed in the order create, add, edit, cat, rebuild, status.

CONFIGURATION

integration.autocontinue: Sets the default for the --autocontinue option.
integration.autorebuild: Automatically rebuild the integration branch after creating/editing it if --no-rebuild is not specified.
integration.prefix: Sets the default arguments for the --prefix option.

FORMAT OF INSTRUCTIONS

The instruction sheet consists of a series of instructions which begin in column zero, each of which may be followed by indented comments. The following instructions are supported:

base <ref>: Resets the state of the integration branch to the specified revision. This should always be the first instruction in the instruction sheet, and should appear only at the top of the instruction sheet.
merge <ref> [<options>]: Merges the specified ref into the integration branch. Any comments following the instruction are appended to the merge commit’s commit message.

If any options are given after the ref (and on the same line) then these are passed to git merge. This may be useful for specifying an alternative merge strategy for a branch.
. <args…>: Ignores this command and its description. This can be used to remove a branch from the integration branch without needing to delete it and its description from the instruction sheet.

For example, if you need to remove a branch until it is in better shape but don’t want to lose track of it, you can simply add ‘`. ’ to the beginning of that branch’s 'merge line.

Example

base master

merge my-experimental-feature

  I think this is a good idea, but want to dogfood it before I
  decide whether to submit it upstream.

merge my-site-specific-changes

  Some changes to suit my environment.  DO NOT SUBMIT THESE.

STATUS FORMAT

Each branch included in an integration branch can have one of four states:

Merged to base: meaning that the branch is included in the branch on which the integration branch is based. This branch can be removed from the integration branch’s instruction sheet without changing the content of the branch.
Up-to-date: meaning that the branch is included in the integration branch but not in the branch on which it is based and that the integration branch contains all of the commits on the branch.
Out-of-date: meaning that the integration branch does not include all of the commits on the branch, because either the integration branch has not been rebuilt since this branch was added to its instruction sheet or the branch has changed since the integration branch was last built.
Not found: meaning that the branch specified in the instruction sheet cannot be found. This may be because the branch does not exist or because it has been deleted for some reason. An integration branch containing branches in this state cannot be rebuilt until the affected branches are removed from the instruction sheet.

These states are indicated by the character places before the branch, as well as a textual indicator following the branch name:

+ merged-to-base  (merged to base)
* up-to-date      (up-to-date)
- out-of-date     (branch changed)
. not-found       (branch not found)

The status output respects the color.status Git configuration variable.

SHARING INSTRUCTION SHEETS

The instruction sheet is just another Git branch, except that it is under refs/insns/ and not refs/heads/. This means that they can be shared in the same way as other branches.

For example, to push the instruction sheet for pu:

git push origin refs/insns/pu