libra remote

Manage configured remotes: list, add, remove, rename, inspect and mutate URLs, and prune stale remote-tracking refs.

Synopsis

libra remote <subcommand> [OPTIONS] [ARGS]
libra remote show
libra remote -v
libra remote add [-f | --fetch] [-t | --track <branch>]... [-m | --master <branch>] [--tags | --no-tags] [--mirror] <name> <url>
libra remote remove <name>
libra remote rename <old> <new>
libra remote get-url [--push] [--all] <name>
libra remote set-url [--add | --delete] [--push] [--all] <name> <value>
libra remote prune [--dry-run] <name>
libra remote update [-p | --prune] [<group> | <remote>...]

Description

libra remote manages the set of named remotes stored in the SQLite configuration database. Each remote has one or more fetch URLs and optionally separate push URLs. Subcommands allow full CRUD operations on remotes and their URLs, as well as pruning stale remote-tracking branches that no longer exist on the remote.

Remote configuration is stored as remote.<name>.url and remote.<name>.pushurl keys in the SQLite config table, rather than in a flat .git/config file. This provides transactional safety (no partial writes on crash) and makes remote metadata queryable by agents and tooling.

Options

Subcommand: show

With no name, lists configured remote names, one per line. With a <name>, prints detailed information about that remote: configured fetch/push URLs, the remote HEAD branch, the remote branches, and the local branches/refs configured for pull/push. By default it contacts the remote (like git remote show): the HEAD is the live default branch, branches are classified tracked / new / stale against the local remote-tracking refs, and queried is true.

Branch classification (online): tracked (advertised by the remote and already fetched), new (advertised but not yet fetched — a later fetch stores it), stale (fetched locally but no longer advertised — libra remote prune removes it). When the remote is unreachable, show fails with a hint to retry with --no-query. For multi-remote fetching, see the update subcommand.

Subcommand: -v (list verbose)

List every remote with its fetch and push URLs.

Subcommand: add

Register a new remote.

The --mirror marker is informational: Libra does not write a +refs/*:refs/* fetch refspec because libra fetch is not yet mirror-aware (matching libra clone --mirror).

Subcommand: remove

Delete a remote and all its configuration keys.

Subcommand: rename

Rename an existing remote.

Subcommand: get-url

Print URLs configured for a remote.

Subcommand: set-url

Add, replace, or delete URLs for a remote.

Subcommand: prune

Delete local remote-tracking branches that no longer exist on the remote.

Subcommand: update

Fetch from one or more remotes. With no arguments, every configured remote is fetched; otherwise each argument is a remote name, or a remotes.<group> config entry that expands to that group's member remotes.

-p / --prune runs the same prune logic as libra remote prune <name>, but only after every resolved remote has fetched successfully (a two-pass fetch-all-then-prune, so a later fetch failure never strands an earlier prune), reporting any removed refs as * [pruned] <name>/<branch>.

Subcommand: set-branches

Set the branches tracked by a remote by rewriting its remote.<name>.fetch refspecs. Each branch becomes +refs/heads/<branch>:refs/remotes/<name>/<branch>.

Subcommand: set-head

Set or delete a remote's default branch pointer (refs/remotes/<name>/HEAD).

The three modes (<branch>, --delete, --auto) are mutually exclusive. Both set-head <branch> and --auto require the resolved branch's tracking ref refs/remotes/<name>/<branch> to already exist (fetch it first); --auto additionally contacts the remote to discover its default branch. remote update [-p|--prune] [<group>|<remote>...] fetches all configured remotes (or the named ones, expanding any remotes.<group> config); -p/--prune then prunes stale remote-tracking branches after every fetch succeeds.

Common Commands

libra remote show
libra remote show origin
libra remote -v
libra remote add origin https://example.com/repo.git
libra remote get-url origin
libra remote get-url --all origin
libra remote set-url --add origin https://mirror.example.com/repo.git
libra remote set-url --add --push origin ssh://[email protected]/repo.git
libra remote prune --dry-run origin
libra remote set-branches origin main dev
libra remote set-head origin main
libra remote set-head origin --auto
libra remote set-head origin -d
libra remote show origin
libra remote show --no-query origin

Human Output

• remote show (no name) prints configured remote names, one per line.
• remote show <name> queries the remote and prints a detailed report (branches classified tracked / new / stale):

* remote origin
  Fetch URL: https://example.com/repo.git
  Push URL: https://example.com/repo.git
  HEAD branch: main
  Remote branches:
    main tracked
    feature-x new (next fetch will store in remotes/origin)
    old-topic stale (use 'libra remote prune' to remove)
  Local branches configured for 'git pull':
    (none)
  Local refs configured for 'git push':
    (none)

• remote show --no-query <name> stays offline; it prints Remote branch data: cached and reports cached tracking branches with the cached status.

• remote -v prints every fetch URL and effective push URL:

origin  https://example.com/repo.git (fetch)
origin  ssh://[email protected]/repo.git (push)

• remote add prints Added remote 'origin' -> https://example.com/repo.git
• remote remove prints Removed remote 'origin'
• remote rename prints Renamed remote 'origin' to 'upstream'
• remote get-url prints the selected URL set, one per line
• remote set-url prints a confirmation describing whether a URL was added, replaced, or deleted
• remote prune prints each pruned branch and a final summary; --dry-run uses [would prune]

 * [would prune] origin/stale-feature
 * [would prune] origin/old-experiment

Would prune 2 stale remote-tracking branch(es).

Structured Output (JSON examples)

• --json writes one success envelope to stdout
• --machine writes the same schema as compact single-line JSON
• action-specific payloads are tagged with data.action

Action Schemas

• add: name, url
• remove: name
• rename: old_name, new_name
• list: verbose, remotes[]
• urls: name, push, all, urls[]
• set-url: name, role, mode, urls[], removed
• prune: name, dry_run, stale_branches[]
• update: remotes[] (names fetched), pruned[] (each {remote_ref, branch}; present only with -p/--prune and omitted entirely when nothing was pruned)
• show: name, fetch_urls[], push_urls[], head_branch, remote_branches[] (each {branch, status, local_oid, remote_oid}; status is tracked/new/stale online or cached with --no-query), pull_config[], push_config[], queried (true when the remote was contacted, false with --no-query)
• set-branches: name, added, fetch_refspecs[]
• set-head: name, mode (set/delete), target

Example (verbose list):

{
  "ok": true,
  "command": "remote",
  "data": {
    "action": "list",
    "verbose": true,
    "remotes": [
      {
        "name": "origin",
        "fetch_urls": ["https://example.com/repo.git"],
        "push_urls": ["ssh://[email protected]/repo.git"]
      }
    ]
  }
}

Example (prune dry-run):

{
  "ok": true,
  "command": "remote",
  "data": {
    "action": "prune",
    "name": "origin",
    "dry_run": true,
    "stale_branches": [
      {
        "remote_ref": "refs/remotes/origin/stale-feature",
        "branch": "origin/stale-feature"
      }
    ]
  }
}

Schema Notes

• list.remotes[].fetch_urls contains all configured fetch URLs
• list.remotes[].push_urls contains effective push URLs; when no explicit pushurl is configured it falls back to fetch URLs
• prune.stale_branches[].branch is the user-facing short name such as origin/feature
• remote show currently maps to action = "list" with verbose = false

Design Rationale

Why SQLite-backed remote storage?

Git stores remote configuration in the flat-file .git/config using INI-style syntax. This format is easy to hand-edit but has no transactional guarantees: a crash mid-write can leave the file truncated or corrupt. Libra stores remotes in SQLite (config table), which provides ACID transactions, concurrent-read safety, and structured queries. An agent can enumerate all remotes with a single SQL query instead of parsing INI syntax. The trade-off is that remotes are not directly editable with a text editor, but libra remote subcommands and libra config provide full programmatic access.

Why a show subcommand?

Git overloads git remote (no subcommand) to list remote names and git remote -v for verbose output. Libra makes listing explicit via remote show (names only) and remote -v (verbose with URLs). The show subcommand provides a clear, discoverable entry point for agents that need to enumerate remotes without parsing verbose URL output. It also avoids the ambiguity of a bare command that means different things depending on flags.

Why multi-URL support?

A single remote can have multiple fetch URLs and separate push URLs. This enables mirror-push workflows (push to GitHub and a self-hosted GitLab simultaneously) and read-from-cache patterns (fetch from a local mirror, push to the canonical remote). The set-url --add and set-url --delete flags manage URL lists without requiring manual config editing. The get-url --all flag exposes the full URL set for inspection. Push URLs (pushurl) take precedence when configured; otherwise, fetch URLs are used for both fetch and push, matching Git's behavior.

Parameter Comparison: Libra vs Git vs jj

Error Handling