libra pull

Fetch objects from a remote and integrate the fetched branch into the current branch.

Synopsis

libra pull [--ff-only] [--ff] [--no-ff] [--squash] [--no-commit] [--commit] [--autostash] [--no-progress] [--rebase] [--no-rebase] [--depth <n>] [<repository> [<refspec>]]

Description

libra pull combines fetch and the same merge engine used by libra merge. It downloads new objects, updates remote-tracking refs, and then integrates the selected upstream into the current branch.

With --rebase (-r), the integration step instead replays local-only commits on top of the fetched upstream tip. This is equivalent to libra fetch followed by libra rebase <upstream>.

With --ff-only, pull fetches the upstream but refuses to create a merge commit when local and remote histories have diverged. Fast-forward and already-up-to-date pulls still succeed. --ff-only conflicts with --rebase, --ff, and --no-ff.

With --no-ff, pull always records a real merge commit even when the upstream could be fast-forwarded, mirroring git pull --no-ff. --ff explicitly allows the default fast-forward behaviour. --ff, --no-ff, and --ff-only are mutually exclusive and conflict with --rebase.

With --depth <n>, the fetch phase is limited to a shallow history of n commits per tip before integration, mirroring git pull --depth. --depth is fetch-only and conflicts with --rebase.

When invoked with no arguments, the command reads the current branch tracking configuration (branch.<name>.remote and branch.<name>.merge). When <repository> is given alone, the current branch name is used as the remote branch. When both <repository> and <refspec> are given, the specified remote branch is fetched and merged.

Pull supports already-up-to-date, fast-forward, and single-head three-way merge results. If the local and remote branches conflict, pull returns the merge-owned LBR-CONFLICT-002 error with phase: "merge" and leaves the same merge state that libra merge uses. Resolve conflicts with libra add <path> and libra merge --continue, or run libra merge --abort.

With --squash, pull fetches and computes the merge but stages the merged tree without creating a commit or moving HEAD, leaving the result ready for a plain libra commit (mirroring git pull --squash). With --no-commit, pull performs the merge and stages the result but stops before committing, recording merge state so the two-parent commit can be finalized with libra merge --continue. --squash and --no-commit conflict with each other and with --rebase. --commit forces a merge commit (the default merge behavior) and is last-one-wins with --no-commit (the final flag on the command line decides); it conflicts with --squash and --rebase, matching git pull --commit.

With --autostash, pull stashes your tracked working-tree changes before integrating (so a dirty tree does not block the merge/rebase) and re-applies them afterwards — even if the merge/rebase fails. Untracked and ignored files are left in place. If re-applying the stash conflicts, the stash is kept and the failure is reported; recover it with libra stash pop.

Options

Examples

libra pull
libra pull origin main
libra pull --ff-only
libra pull --no-ff
libra pull --depth 1
libra pull --rebase origin main

Human Output

Default human mode writes fetch progress to stderr and the pull summary to stdout.

Fast-forward:

From [email protected]:user/repo.git
   abc1234..def5678  origin/main
Updating abc1234..def5678
Fast-forward
 3 files changed

Clean three-way merge:

From [email protected]:user/repo.git
   abc1234..def5678  origin/main
Updating abc1234..def5678
Merge made by the 'three-way' strategy.
 2 files changed

Already up to date:

From [email protected]:user/repo.git
Already up to date.

No tracking information:

There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    libra pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    libra branch --set-upstream-to=origin/<branch> main

Rebase:

From [email protected]:user/repo.git
   abc1234..def5678  origin/main
Successfully rebased 2 commits onto 'origin/main' (1111111..2222222).

--quiet suppresses all progress and merge summary output.

Structured Output

--json writes one success envelope to stdout. --machine writes the same schema as one compact JSON line. Success leaves stderr clean.

{
  "ok": true,
  "command": "pull",
  "data": {
    "branch": "main",
    "upstream": "origin/main",
    "fetch": {
      "remote": "origin",
      "url": "[email protected]:user/repo.git",
      "refs_updated": [
        {
          "remote_ref": "refs/remotes/origin/main",
          "old_oid": "abc1234...",
          "new_oid": "def5678..."
        }
      ],
      "objects_fetched": 12,
      "bytes_received": 2048
    },
    "merge": {
      "strategy": "three-way",
      "old_commit": "abc1234...",
      "commit": "def5678...",
      "files_changed": 2,
      "up_to_date": false,
      "parents": ["abc1234...", "fedcba9..."]
    }
  }
}

Rebase output omits merge and includes rebase:

{
  "ok": true,
  "command": "pull",
  "data": {
    "branch": "main",
    "upstream": "origin/main",
    "fetch": {
      "remote": "origin",
      "url": "[email protected]:user/repo.git",
      "refs_updated": [],
      "objects_fetched": 0,
      "bytes_received": 0
    },
    "rebase": {
      "status": "completed",
      "old_commit": "1111111...",
      "commit": "2222222...",
      "replay_count": 2,
      "up_to_date": false
    }
  }
}

Schema Notes

• branch is the current local branch being updated.
• upstream is the remote tracking branch name, such as "origin/main".
• fetch.refs_updated lists remote refs that changed during fetch.
• Exactly one of merge or rebase is present, depending on whether --rebase was passed.
• merge.old_commit is the pre-merge HEAD; it is null on the first pull into an empty local branch.
• merge.strategy is "fast-forward", "three-way", or "already-up-to-date".
• merge.commit is the new HEAD commit after merge; it is null when up to date.
• merge.parents appears for successful three-way merge commits.
• merge.files_changed is the number of paths changed by the merge result.
• rebase.status is "completed", "fast-forwarded", "already-up-to-date", or "no-commits".
• rebase.replay_count is the number of local commits replayed onto the upstream tip.
• rebase.up_to_date is true when the rebase did not move HEAD.

Parameter Comparison: Libra vs Git vs jj

Error Handling

Every PullError variant maps to an explicit StableErrorCode. Fetch, merge, and rebase sub-errors are forwarded with a phase detail for diagnostics.

Phase Detail

When a sub-operation fails, the error JSON includes a phase key in the details object ("fetch", "merge", or "rebase") so agents can distinguish which stage failed.