# Git Pull Method

> Chooses how Pull brings the remote commits into your branch when it is behind: Fast-forward only (the default, never creates a commit and stops when your branch and the remote both have new commits), Merge (creates a merge commit when both sides moved) or Rebase (replays your local commits on top of the remote ones, linear history).

- Area: Desktop app
- Plans: All plans
- Last checked against the product: 2026-10-12
- Web page: https://agentsroom.dev/docs/git-pull-method

## What it does

Chooses how **Pull** brings the remote commits into your branch when it is behind: **Fast-forward only** (the default, never creates a commit and stops when your branch and the remote both have new commits), **Merge** (creates a merge commit when both sides moved) or **Rebase** (replays your local commits on top of the remote ones, linear history). The same choice drives every pull in the app: the **Remote changes detected** window and the Pull button of the Changes tab.

## Where to find it

- The **Remote changes detected** window (shown when the branch is behind its remote): the **Pull method** list sits above the Pull button. Picking a method there is saved on the project straight away.
- Project settings > **Git** > **Pull method**: the project's own choice, with a reset link to go back to the global one.
- Settings > **Git** > **Pull method**: the default for every project.

## How to use it

1. Open the **Remote changes detected** window, or Project settings > Git.
2. Pick **Fast-forward only**, **Merge** or **Rebase**.
3. Click **Pull changes**. If a fast-forward was refused because both sides moved, the window says so: pick **Merge** or **Rebase** and pull again, nothing was changed by the failed attempt.

A pull that stops on a conflict (merge or rebase) leaves the repository in the middle of the operation, like in a terminal: the window then offers to hand it to a Git expert agent or to open a terminal.

## Settings

- `gitPullStrategy` (global, Settings > Git > **Pull method**, `ff-only` by default, synced with your account): `ff-only`, `merge` or `rebase`.
- `gitPullStrategy` (project override, Project settings > Git > **Pull method**): same values; unset means it inherits the global one. The Remote changes detected window writes this one.

## Agent tools (MCP)

- `settings_get` / `settings_set` with key `gitPullStrategy` (scope `global` or `project`).

## Providers

All providers, no difference. It is plain git, not an agent feature.

## Mobile

Not on the mobile companion: pulling a repository is a desktop action there.

## Limits

Works the same on macOS, Windows and Linux. With Rebase or Merge, uncommitted local changes can block the pull (git refuses): commit or stash them first.

## Common questions

- **Can I pull with rebase instead of merge?** Yes: Pull method > **Rebase**, globally in Settings > Git or per project.
- **Why does the pull say a fast-forward is not possible?** Your branch and the remote both have new commits. Choose **Merge** or **Rebase** and pull again.
- **Pull or Push failed in the Changes tab: where is the full error?** Under the Changes header: git's complete message stays there until you close it (X). You can select it or copy it with the copy button. Success messages still disappear on their own.
- **Does my choice apply to other projects?** No, picking a method in the window saves it for that project only. The global default is in Settings > Git.

## Related

- [AI Commit Messages](https://agentsroom.dev/docs/ai-commit-messages.md): the other Git tab settings.