gritHEAD → docs/sync
Commands / RemotesMarkdown

grit sync

Push and pull every active branch between a clone and your space on a grit hosting server.

grit sync

Description

On a grit hosting server such as GitButler Code, your work on a project lives in your space, <you>/<project>, private to you. An organization's projects (<domain>/<project>) are read-only: you work in a copy of one in your space, which follows the organization's branches, and integrate from there.

grit sync, in a clone of a project on such a server:

  1. asks the server where your work goes: the project in your space for the one origin names. For an organization's project, the server makes your copy when you have none yet. The clone is then set up to push there: a space remote fetches from it, and remote.origin.pushurl points at it, so a plain grit push (or git push) sends branches to your space while fetches still come from the organization. grit clone of a GitButler Code project does this setup too, when you are signed in;
  2. fetches origin and your space;
  3. fast-forwards the target branch (the branch work is integrated into, usually main) to the project's. A target with commits of its own is left alone: it changes only by integrating;
  4. brings down your space's branches: one you don't have here is made, tracking your space's; one that is behind is fast-forwarded (when it is checked out, the working tree follows, as grit merge --ff-only would);
  5. pushes every active branch to your space: every branch but the target, the branches your space follows from upstream (read-only there), and branches already merged into the target, such as one you integrated.

A branch that has commits here and in your space that the other lacks is left alone and reported as diverged: switch to it, run grit pull --rebase, and sync again. Nothing is ever force-pushed.

Shared branches

A branch you share with other people works differently, because each member has their own head of it and only you move yours:

  • the other members' heads are fetched too, as <remote>/shared/<branch>/<user>, and reported under the branch with how each compares with yours;
  • when another member's head builds on yours, your branch is fast-forwarded to it (to the furthest such head, when they are on one line) and then pushed as your head (took bob's head, which builds on yours);
  • when your branch here and your head in your space have diverged (you amended or rebased here), your head is replaced: it is yours alone, and the server keeps the old one in the share's log;
  • a member's head that has diverged from yours, but goes together with it without losing anything, is combined with yours, and the result pushed (combined with bob's head, ...). One that needs a decision is reported with its options (see grit share resolve), and sync exits 3.

Sync works in a clone. In a snapshot checkout, send branches with grit checkin and update with grit pull. You need to be signed in to the server (grit login).

Options

grit sync takes no options besides the global options.

JSON output

Schema: v1

Field Type Meaning
space string Your space's project, <you>/<project>.
upstream string or omitted The project it follows, for a copy of an organization's project.
remote string The remote branches are pushed to and pulled from: origin when it is your space, else space.
configured boolean Whether this run set the clone up to push to your space.
target object or omitted The target branch: name, action (up_to_date, fast_forwarded, created, ahead or diverged) and tip.
branches array Each active branch: name, action (pushed, pulled, created, up_to_date, diverged or refused), tip, a message for a divergence or refusal, and for a shared branch shared: the other members' heads, each with user, tip, relation to your branch (same, ahead, behind, diverged or unknown), and for a head that diverged from yours divergence: scenario (a stable code such as amended_both_conflicting; see Divergence scenarios), summary, needs_decision, base, changes (each commit's change, subject, and what you and them did to it), conflicts and also. For a branch the sync made again after a share of it was integrated, integrated: the pushed_to_integrated report, as grit push has it.

Markdown output

Pass --markdown for agent-friendly output.

Schema: v1

Exit status

Code Meaning
0 Every active branch is in step with your space.
1 A branch diverged or a push was refused (the output names it), the target diverged from upstream, or sync could not run: not a clone of a hosted project, not signed in, or this is a snapshot checkout.
3 Everything else is in step, but another member's head of a shared branch diverged from yours in a way someone has to decide about, or a branch was pushed again after it was integrated (pushed_to_integrated) (needs_decision).