Sync, push & pull

Birch fetches every active repository automatically every five minutes; the rest of remote traffic is yours to drive. This page covers pull strategies, publishing a workspace branch before its PR, and why the only force-push Birch offers is --force-with-lease.

Automatic fetch

A background scheduler runs git fetch --prune on each active repository roughly every 5 minutes. This is local-only bookkeeping — it never pulls, pushes, or touches your working copy; it just keeps ahead/behind counts and the commit graph current.

Fetch and Pull

The Git view’s header (in a workspace’s Git tab) shows one fetch/pull slot next to the Push button:

• Fetch — shown while your branch is up to date with (or ahead of) its upstream. Fetches the worktree’s remote without pulling.
• Pull — the same slot swaps to a Pull button with a ↓n badge as soon as the branch is behind its upstream by n commits.

A repository page’s header also has a Fetch button for fetching without opening the Git view. Successful pulls confirm with a toast (“Pulled n commits from origin”).

Pull strategies

The Pull dropdown in the Changes tab’s commit area picks how git pull reconciles your branch (tooltip: Strategy used when pulling — remembered per repository):

Strategy	Git behavior
Default	Plain git pull — your git configuration decides
Rebase	git pull --rebase
Merge	git pull --no-rebase
FastForwardOnly	git pull --ff-only — aborts instead of creating a merge commit

The choice is stored per repository, so a rebase-first project and a merge-first project can coexist. If a pull hits conflicting changes, Birch opens the conflict resolver automatically.

Push and Publish

The header’s Push button pushes your branch and shows an ↑n badge while you have n unpushed commits. When the branch has no upstream yet — a fresh workspace branch, for example — the same button reads Publish and runs git push --set-upstream, creating the remote branch and wiring tracking in one step.

Publishing or pushing a workspace branch is the natural step right before creating its pull request; the Create PR button sits beside Push in the same header, and a successful push also refreshes the branch’s PR status.

Force push (with lease)

When your branch has diverged — commits both ahead of and behind its upstream, typically after an amend or rebase of pushed history — a Force push (with lease) button appears in the Changes tab’s commit area. It asks for confirmation, then runs a force-push with --force-with-lease.

Danger

Force-pushing rewrites the remote branch. The lease makes it the safe variant: git refuses the push if the remote has moved past what your last fetch saw, so you cannot silently overwrite commits a teammate pushed in the meantime. Birch never offers a plain --force.

Credentials

Birch drives the git CLI, so pushes and pulls authenticate exactly as git does on your machine: your credential helper, per-host HTTPS tokens, or an SSH key. All three are managed in Settings → Integrations — see Git credentials.

When something goes wrong

• Errors are shown inline. A failed fetch, pull, or push surfaces git’s error message next to the header buttons; nothing is retried silently.
• “No upstream” is not an error — the Push button simply becomes Publish.
• Rejected push (the remote moved while you worked): Fetch or Pull first, resolve what arrived, and push again. Only if you rewrote history deliberately should you reach for Force push (with lease) — and it only appears once the branch is genuinely diverged.