---
name: git-remotes

description: >
  Use when a git operation — remote config, fetch, push, or pull — touches a
  remote, even when the user does not name it.
  Not local commits -> `git-commits`.
  Not local branches -> `git-branches`.
  Not log or bisect queries -> `git-history`.
  Not submodule pointers -> `git-submodules`.

metadata:
  version: "1.0.3"
  category: git
  source_keys:
    - git-scm-remote-docs
    - git-scm-fetch-docs
    - git-scm-push-docs
    - git-scm-pull-docs
    - context7-git-htmldocs
---

## Gotchas

- **`--force-with-lease` alone is not safe** — background processes (IDE plugins, cron jobs) running `git fetch` silently defeat the protection. Combine it with `--force-if-includes`, or pin the explicit `--force-with-lease=<ref>:<sha>` form.
- **Prune does not touch tags by default** — `git fetch --prune` leaves orphaned tags behind. Use `--prune --prune-tags`, or set `fetch.pruneTags true`.
- **Set `pull.ff only` explicitly** — do not trust the installed default.

## Step 1 — Clear the force-push gate

`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing.

## Step 2 — Dispatch

Read the row matching the operation, and only that row — each file is self-contained. A task spanning two operations reads both.

| Operation | Read |
|---|---|
| Add, remove, rename, inspect, or re-point a remote; tracking, mirror, and `set-url` config | `references/remote-config.md` |
| Fetch or prune remote-tracking refs; shallow or partial fetch | `references/fetch.md` |
| Push branches or tags; refspecs; force-push | `references/push.md` |
| Pull — integrate remote changes into the current branch | `references/pull.md` |

## Step 3 — Return format

For agent callers, return:

```json
{
  "success": true,
  "operation": "push",
  "remote": "origin",
  "branch": "main",
  "output": "...",
  "warnings": ["force-with-lease not confirmed"],
  "recommendations": ["set `pull.ff only` so the default does not vary by Git version"]
}
```

On failure, set `success: false` and add an `error` field holding the root cause and a recovery suggestion.