Description
On a grit hosting server such as GitButler Code, your branches are private to your space. grit share lets other people work on one of them with you. A shared branch is in every member's space, and each member has their own head of it: only you move yours. Nobody's push can overwrite anyone else's work, so there is nothing to force, and every head anyone pushes is kept in the share's log on the server.
The other members' heads are fetched beside yours as <remote>/shared/<branch>/<user> (from the server's refs/shared/<branch>/<user>, which nobody pushes to). grit status shows them under your branch, grit sync fast-forwards your branch to a member's head that builds on yours, and grit push replaces your head after an amend or rebase without --force (it still checks that the server's head is the one you last fetched).
grit share add <branch> <user>...shares a branch of your space with people, each of whom is emailed. Name them by user name or email address: an address that belongs to an account adds that account, and any other address is emailed an invitation. The invitation's link asks them to create an account, then shows them how to work on the branch with grit or plain git; it works once, for 30 days. A branch that isn't in your space yet, or differs there, is pushed first. Anyone on the branch can add people. Someone added by name gets their copy of the project (with the branch in it) the first time they fetch from their space:grit clone https://<server>/<them>/<project>, orgrit syncin a clone they have.--no-historyand--path <path>make it a snapshot share for the people added (and the link): the branch's own history, without the rest of the project's, cut down to those paths.--linkmakes a share link instead (or as well): a URL anyone signed in can accept, in the browser or withgrit share accept. A link works once and for 7 days unless you pass--uses(a number orunlimited) and--expires(1 to 30 days). The URL is shown only now; the server keeps only its hash.grit share listshows your shared branches: who is on each, where each head is, and how it compares with your branch here (same as yours,has commits you don't,behind yours,diverged from yours), and any open links.grit share accept <link>accepts a link: you are on the branch, and your copy of the project is made in your space. In a clone of the project it fetches the branch into it; anywhere else it clones your copy into a new directory.grit share remove <branch> <user>...removes people, and withdraws invitations to the email addresses you name. Only the person who shared the branch (or, for a copy of an organization's project, someone who can integrate into it) can remove people, and nobody can remove the person who shared it. With no users, it ends the share. Nobody loses work: each member's head stays a branch in their own space.grit share leave <branch>takes you off a branch; your head stays a branch in your space.grit share resolve <branch> [<option>]puts your head and another member's back together after they diverged (see Resolving a divergence). Name the member with--withwhen several heads diverged from yours. For a branch pushed again after it was integrated, it takesrebase,rename <name>orreshare(see After integrating).grit share revoke <branch> <link-id>stops a link from working. Link ids are ingrit share list.
Your copy
When the project is a copy of an organization's project, everyone's copy is a copy of that organization's project. Otherwise each member's copy holds just the shared branches and the sharer's default branch, read-only, as the base they build on; the sharer's other branches stay private.
When heads differ
grit sync compares your branch with every other member's head:
- one that builds on yours: your branch is fast-forwarded to it (to the furthest such head, when they are on one line), and your head is pushed;
- one that your branch builds on: nothing to do;
- one that has diverged from yours: reported. Rebase onto it with
grit rebase <remote>/shared/<branch>/<user>(or have them rebase onto yours) and sync again.
Divergence scenarios
When another member's head has diverged from yours, grit sync, grit status, grit share list and grit push say what happened, commit by commit: for each commit, what you did and what they did (unchanged, moved, reworded, amended, dropped, squashed, split, new), matched by change id. The situation gets one of these codes, which scripts and agents can rely on. Some can be put together without losing anything; the rest need someone to decide, and grit push and grit sync exit with status 3 for them.
| Scenario | What happened | Needs a decision |
|---|---|---|
added_both |
You both added commits on top of the same base, and they don't conflict. | no |
rewrote_one |
One of you rewrote commits (amended, reordered, split, squashed or dropped); the other only added on top. | no |
amended_both_compatible |
You both amended the same commit, without overlapping (or one changed only its message). | no |
amended_one_reordered_other |
One reordered commits; the other amended one of them. | no |
amended_different |
You each amended different commits. | no |
rebased_one |
One rebased onto a newer target; the other only changed commits. | no |
rebased_both |
You both rebased, onto different target commits. | no |
dropped_one |
One dropped a commit the other didn't touch. | no |
dropped_both |
You both dropped the same commit. | no |
split_one |
One split a commit the other didn't touch. | no |
squashed_one_added_other |
One squashed commits; the other added on top. | no |
squashed_one_amended_other |
One squashed a commit into another; the other amended it. | no |
split_one_amended_other |
One split a commit; the other's amendment of it fits one piece. | no |
amended_both_conflicting |
You both amended the same commit, and the edits overlap. | yes |
added_both_conflict |
You both added commits, which conflict with each other. | yes |
dropped_one_amended_other |
One deleted a commit; the other amended it. | yes |
reordered_both |
You both reordered the commits, into different orders. | yes |
split_both |
You both split the same commit, differently. | yes |
split_one_amended_other_spanning |
One split a commit; the other's amendment of it spans the pieces. | yes |
squashed_both_differently |
You both squashed commits, differently. | yes |
reset_one |
One head drops most of the branch, with or without new commits on top: perhaps an accidental reset. | yes |
merge_commit |
One head has a merge commit. | yes |
no_change_ids |
Commits made or rebased with plain git have no change ids, so an amend can't be told from a new commit. |
yes |
Heads that haven't diverged are same, ahead, behind, same_content (the same changes as different commits) or same_rewrite (the same amend, drop or squash on both sides).
The comparison starts from the last head you both had, read from the reflogs of your branch and of their head here; without one, from where the two heads meet. Use grit commit and grit rebase, which keep change ids, so commits can be followed across amends.
Resolving a divergence
Every divergence report lists its options, the recommended one first, each with the command that applies it and what it leaves out (loses, null when it keeps every change). What an option leaves out is never lost: every head anyone pushed stays in the share's log on the server.
| Option | What it does |
|---|---|
combine |
Every change from both heads, commit by commit: their commits kept as they are where possible, yours replayed on top, so they can fast-forward to the result. |
keep_both |
For a commit you both amended, differently: their head as it is, then your version as a commit of its own on top, so they can fast-forward to the result. |
keep_amended / drop |
For a commit one of you dropped and the other amended: keep the amended version, or drop it. |
my_order / their_order |
When you both reordered the commits. |
my_split / their_split |
When you both split a commit. |
restore |
When one head dropped most of the branch: the head that kept it, as it is, with the other head's new commits on top. |
keep_mine / keep_theirs |
One head as it is. |
resolve |
By hand: rebase onto their head (grit rebase <remote>/shared/<branch>/<user>), settle the conflicts, grit rebase --continue, and grit push. |
grit share resolve <branch> with no option applies combine when nothing would be lost; otherwise it lists the options and exits with status 3. With an option, it moves your branch to the result (when the branch is checked out, as grit reset --keep does, keeping local changes or refusing) and pushes your head.
Without asking. When another member's head and yours can be put together without losing anything (any scenario that doesn't need a decision), grit sync and grit push do it themselves: they combine the two, move your branch, and push the result, and the other member's next grit sync fast-forwards to it. Only when someone has to decide do they stop, report the options, and exit 3.
Snapshot shares
grit share add <branch> bob --path src/rpc (or --no-history alone, for the whole tree) shares the branch without the project's history. bob's copy is a project of its own in his space that holds only what he may see:
- its base branch (
main) is a snapshot: one commit standing for the base where the branch starts, cut down to his paths. Each path brings everything under it, plus the files directly in each directory above it (as Git's cone-mode sparse checkout does); - the branch, and the other members' heads under
origin/shared/<branch>/<user>, are their commits projected onto the snapshot, cut down the same way. So he has the branch's history, not the project's; - when the base moves, his next fetch brings a new snapshot of it on top of the last one, and
grit syncfast-forwards his base branch to it; to build on it, he rebases his branch onto it (grit rebase origin/main), as anyone would. His base branch is read-only.
He works with grit or plain git as usual. What he pushes is grafted back onto the real history as his head, so everyone with the whole branch gets full commits, with the files outside his paths as they were. A push that would undo changes outside his paths stays in his space, unshared, and the push's remote: lines say why with the code outside_paths:
- rewriting a commit (an amend, a rebase that drops it) that also changed files outside his paths. Add new commits on top instead;
- a commit that changes a file the base now holds differently outside his paths. Rebase onto the newest snapshot first.
A member with a snapshot share can add people only with the same view, and can't integrate the branch: someone with the whole branch does.
After integrating
grit integrate on a shared branch merges your head, once every other member's changes are in it (or the members whose aren't are left out with --without). Then the share is over: the branch is deleted from every member's copy and the server's refs/shared/ heads with it, and everyone is told. Your clone keeps its local branch; grit sync leaves it alone once its commits are on the target.
The server remembers the integration for 14 days. When a push or sync makes a branch of that name again and it brings commits that were integrated (by change id), it is pushed as a branch nobody shares, and grit push and grit sync report it with scenario pushed_to_integrated, how many of its commits were integrated and how many are new, and these options (exit status 3). Reusing the name for unrelated work gets no report.
| Option | What it does |
|---|---|
rebase |
Replay only the new commits onto the target (origin/<target>), leaving out every commit that was integrated, even amended since, and push the branch. |
rename <name> |
Rename the branch here and in your space, deleting the old name there. |
reshare |
Share it again with everyone who was on it. |
Plain git sees the same report as remote: lines on the push.
Options
| Option | Description |
|---|---|
--link |
add: make a share link anyone signed in can accept. |
--uses <n> |
add --link: how many times it can be accepted, or unlimited. Default 1. |
--expires <days> |
add --link: how many days it works, 1 to 30. Default 7. |
--no-history |
add: a snapshot share, without the project's history. |
--path <path> |
add: a snapshot share of only this path (implies --no-history). Repeatable. |
JSON output
Schema: share.add v1 · share.list v1 · share.accept v1 · share.remove v1 · share.leave v1 · share.revoke v1 · share.resolve v1
grit share add, list, remove, leave and revoke have the same shape:
| Field | Type | Meaning |
|---|---|---|
action |
string | add, list, remove, leave or revoke. |
project |
string | Your project the shares are in, <you>/<project>. |
shares |
array | Each shared branch: branch, origin, sharer, state (active, integrated, ended), mode (full), base_branch, members (user, sharer, you, head, project, relation to your branch: same, ahead, behind, diverged, unknown, for a diverged head divergence, as in grit sync, and for a snapshot member snapshot, the paths they see, empty for the whole tree), invited (email addresses that haven't accepted yet), links (id, uses_left, expires_at, and snapshot for a snapshot share link) and url. |
link |
object or omitted | The link add --link made: id, url, uses_left, expires_at, and snapshot (its paths) for a snapshot share link. |
added |
array or omitted | People added, who were emailed: user names, and the email addresses invited. |
removed |
array or omitted | People removed (or you, when leaving), and the email addresses whose invitations were withdrawn. |
pushed |
boolean or omitted | Whether the branch was pushed to your space first. |
grit share accept:
| Field | Type | Meaning |
|---|---|---|
status |
string | accepted or already_member. |
branch |
string | The shared branch. |
sharer |
string | Who shared it. |
origin |
string | The project it was shared from. |
project |
string | Your copy, <you>/<project>. |
url |
string | Your copy's clone URL. |
path |
string or omitted | The clone it was fetched into, or cloned as. |
cloned |
boolean | Whether this made a new clone. |
grit share resolve:
| Field | Type | Meaning |
|---|---|---|
branch |
string | The shared branch. |
with |
string | The member whose head yours was put together with. |
scenario |
string | What the two heads added up to, before. |
summary |
string | What happened, in a sentence. |
option |
string or omitted | The option applied; omitted when a decision is needed and none was chosen. |
previous |
string | Your head before. |
head |
string or omitted | Your head afterwards, when it moved. |
pushed |
boolean | Whether your head was pushed. |
next |
string or omitted | What to run next, for resolve, which is done by hand. |
options |
array or omitted | When a decision is needed and none was chosen: each option's id, label, loses and command. |
renamed |
string or omitted | For rename: the branch's new name, here and in your space. |
shared_with |
array of strings or omitted | For reshare: who the branch is shared with again. |
Markdown output
Pass --markdown for agent-friendly output.
Schema: share.add v1 · share.list v1 · share.accept v1 · share.remove v1 · share.leave v1 · share.revoke v1 · share.resolve v1
Exit status
| Code | Meaning |
|---|---|
0 |
Done. |
1 |
The server refused (the message says why: not on the branch, only the sharer can remove people, a used-up or expired link), the option chosen conflicts, or the command could not run: not a clone of a hosted project, not signed in. |
3 |
grit share resolve without an option, for a divergence that needs a decision, or a branch pushed again after it was integrated: the options are listed (needs_decision). |
2 |
Invalid arguments, such as --uses without --link. |