gritHEAD → docs/share
Commands / RemotesMarkdown

grit share

Work on a branch together with other users of a grit hosting server, each with their own head of it.

grit share add <branch> [<user>|<email>...] [--link [--uses <n>|unlimited] [--expires <days>]] [--no-history] [--path <path>...]
grit share list [<branch>]
grit share accept <link>
grit share remove <branch> [<user>|<email>...]
grit share leave <branch>
grit share resolve <branch> [<option> [<name>]] [--with <user>]
grit share revoke <branch> <link-id>

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>, or grit sync in a clone they have.
  • --no-history and --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.
  • --link makes a share link instead (or as well): a URL anyone signed in can accept, in the browser or with grit share accept. A link works once and for 7 days unless you pass --uses (a number or unlimited) and --expires (1 to 30 days). The URL is shown only now; the server keeps only its hash.
  • grit share list shows 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 --with when several heads diverged from yours. For a branch pushed again after it was integrated, it takes rebase, rename <name> or reshare (see After integrating).
  • grit share revoke <branch> <link-id> stops a link from working. Link ids are in grit 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 sync fast-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.