Description
In a snapshot checkout, the target branch only changes on the server. grit integrate <branch>:
-
checks the branch in first when you have it here, after giving its commits made with plain
gita change id (seegrit checkin); -
merges it into the target branch on the server, with a merge commit by you, when it merges without conflicts. The merge is by the author your own commits get (
GIT_AUTHOR_NAMEandGIT_AUTHOR_EMAIL, thenauthor.*anduser.*config, asgrit commithas it), or the signed-in user when none is set; the server cleans<,>and line breaks out of the name and email. A branch that conflicts is not merged: the error names the files and tells you to rungrit pullon the checkout, then integrate again. A branch the target already has is left alone; -
refreshes this checkout onto the new target, as
grit pulldoes. The branch's commits are in the new snapshot now, but not as its ancestors (a snapshot is one commit standing for the target's tree), so they are never replayed: replaying them one by one could conflict with themselves, as three commits editing one line would against a snapshot that has the last edit. Instead:- when you are on the branch, it moves to the new snapshot, keeping uncommitted and untracked changes as
git reset --keepdoes (refresh.resultislanded); - when you are on a branch built on it, only that branch's own commits are rebased onto the new snapshot, as
git rebase --onto origin/<target> <integrated tip>would; - other branches: one whose commits were all integrated follows to the new snapshot, like a local branch named after the target with no commits of its own; ones with work of their own still on an older snapshot are named, with how to bring each up (
grit switch <branch>, thengrit pull, which leaves the integrated commits out too). WithHEADdetached, onlyorigin/<target>moves.
The checkout remembers the integrated tip (in its marker) until no branch, and no worktree's detached
HEAD, builds on it any more, so later refreshes leave those commits out as well, in any of the checkout's worktrees; - when you are on the branch, it moves to the new snapshot, keeping uncommitted and untracked changes as
-
moves you to a new branch when you were on the branch it merged: the server reserves a fresh work branch name for the checkout (from your
user.email, numbered past names it has given out, asgrit checkoutdoes), and the merged branch is renamed to it. The merged branch is gone here; it stays on the server. New commits then check in as a new branch instead of adding to one the target already has.
The server merges into its current target, the branch its HEAD names, while a checkout follows the branch it was made from. When the two differ (the server's HEAD was moved to another branch since), the merge is not in this checkout's snapshots: the refresh in step 3 treats the branch like any other, nothing is remembered, step 4 is skipped, and the branch keeps its commits here, so refreshes rebase them onto newer snapshots as usual. The output says which branch the checkout follows (follows).
The branch can also be one somebody else checked in or pushed: a plain push to the target itself is refused (see grit serve), so push to another branch and integrate that. Integrating needs write access. Where the server's repository keeps reflogs, the move of the target is logged as integrate: Merge branch '<branch>' into <target>, so git reflog <target> on the server shows it.
These are refused, and the target is left alone:
- the target branch itself (in any case): name the branch to merge into it;
- a name that is not a valid branch name, such as one with
..in it; - a branch the server doesn't have: check it in first;
- a branch that shares no history with the target, such as an orphan branch, or raw checkout commits pushed straight to a branch (they sit on a snapshot commit rather than on the real history): check them in with
grit checkininstead; - a merge that would overwrite uncommitted changes in the server's worktree, when the server's repository has the target checked out: the server's worktree moves with each integration (keeping uncommitted changes there, as
git reset --keepdoes), so commit or stash those changes on the server first.
Integrations, and slice changes, take turns on the server: several at once all merge, each onto the target the one before left. Each is merged again if the target moves while it is made, so none is lost or refused for coming second.
In a clone of a hosted project
In a clone (not a snapshot checkout) of a project on a grit hosting server such as GitButler Code, grit integrate <branch>:
- pushes the branch to your space (
<you>/<project>), asgrit syncwould, setting the clone up for it first when it isn't yet; - asks the server to merge it into the target. For your copy of an organization's project, that is the organization's target branch (usually
main): the server opens a pull request from the branch, or uses the open one, and integrates it at once. Only members of the organization may; anyone else is told to propose the branch instead, with the link. For a project of your own, it is the project's own target branch. A branch that conflicts is refused with the conflicting files, and nothing changes; - fetches
originand fast-forwards the target branch here to the new tip (local).
The branch you are on stays as it is; once merged, grit sync stops pushing it.
A shared branch merges your head of it. Every other member's head has to be in yours first: when one has changes yours doesn't (matched by change id), nothing is merged, and the refusal names each such member and their commits. Take them with grit sync and integrate again, or pass --without <user> to merge without them; their changes stay in their copy, as a branch nobody shares. Once merged, the share is over: the branch is deleted from every member's copy (except the heads of members left out), every member is told, and unshared lists them. The server remembers what was merged for 14 days, so a later push of the branch's name that brings those commits is reported as pushed_to_integrated (see grit share).
Options
| Option | Description |
|---|---|
<branch> |
The branch to merge into the target. |
--without <user> |
For a shared branch: merge without waiting for this member's changes, which stay in their copy. Repeatable. |
JSON output
Schema: v1
| Field | Type | Meaning |
|---|---|---|
name |
string | The branch merged. |
target |
string | The server's target branch. |
status |
string | merged or already_integrated. |
previous |
string | Where the target was. |
head |
string | Where it is now. |
commits |
integer | The branch's commits the merge brought in. |
checkin |
object or omitted | The check-in done first (see grit checkin's JSON). |
refresh |
object or omitted | The refresh done after (see grit pull's JSON); refresh.result is landed when the branch you were on moved to the new snapshot. Omitted when the refresh failed. |
moved_to |
string or omitted | The new work branch you are on, when you were on the branch merged (it is gone here and stays on the server). |
follows |
string or omitted | The branch this checkout follows, when the server merged into another one (target, the branch its HEAD names now): the merge is not in this checkout's snapshots, so the branch keeps its commits here and you stay on it. |
refresh_error |
string or omitted | Why refreshing this checkout after the merge, or moving you to a new branch, failed. The merge stands; the exit status is 1. |
project |
string or omitted | In a clone: the project merged into, <owner>/<project> (the organization's, for your copy of one). |
pull |
integer or omitted | In a clone: the pull request the merge went through, for a copy of an organization's project. |
url |
string or omitted | In a clone: the pull request's web page. |
local |
object or omitted | In a clone: the target branch here after the merge, as grit sync's target reports it (name, action, tip). |
unshared |
array of strings or omitted | For a shared branch: the other members. Integrating ended the share and deleted the branch from their copies. |
Markdown output
Pass --markdown for agent-friendly output.
Schema: v1
Exit status
| Code | Meaning |
|---|---|
0 |
The branch was merged, or the target already had it, and the checkout was refreshed. |
1 |
The branch was merged (or the target had it), but the refresh after failed (refresh_error) or stopped (refresh.result is rebase_stopped, conflicts, refused_not_ff or autostash_conflict): the output says so and what to do. Or nothing was merged: the branch conflicts with the target, shares no history with it, is the target, is not a valid branch name, could not be checked in, or does not exist on the server; uncommitted changes in the server's worktree block the merge; in a clone, you aren't a member of the organization, the branch couldn't be pushed to your space, or it is a shared branch another member's head has changes of that yours lacks (pass --without <user> to merge anyway); or this is neither a snapshot checkout nor a clone of a hosted project. |