Git
Fetch and sync
What the word beside a branch says about its upstream, what a fetch from Pip runs and changes, and how to open a pull request.
What the sync words mean#
The word after a branch name says where that branch stands against the one it tracks — its upstream, usually the branch of the same name on origin. You see it on a server's row (main ↑2), in the server's tray menu, in the Repositories list, and on the Git tab's Remote card, which spells it out. Pip works it out from the files in .git without running git, so it describes your clone as of its last fetch. While a merge or rebase is stopped part-way, the row shows that instead — see Merges and rebases.
- In sync
- The branch and its upstream point at the same commit. The row adds nothing after the branch name; the card says “In sync”.
- ↑2 ↓5
- Two commits on your branch that the upstream does not have, and five on the upstream that yours does not. A side at zero is left out, so
↑2alone is work waiting to be pushed. The card says “2 ahead, 5 behind”. - not synced
- The two point at different commits, but Pip could not count how far apart they are — the next section says why. The card says “Differs from origin/main, count unknown”.
- upstream gone
- The branch tracks a remote branch that is not in this repository — usually deleted on the remote and pruned here by a fetch, though one never fetched looks the same. The card is marked as a warning, with “Upstream branch deleted” and “This branch tracks a remote branch that no longer exists here. Pip can't tell whether it was merged.” The tray menu says it only once Pip has watched the branch go, and so never for a WSL row.
- No comparison
- The row says nothing and the card says “Can't compare with the upstream”: the branch has no commit yet, the remote's fetch settings do not map it to a remote-tracking branch, or a ref could not be read.
- No upstream
- The branch tracks nothing, so the row says nothing and the card says “Not tracking a remote branch” — or “Detached HEAD” when no branch is checked out. Pushing with
git push -usets one.
On the Remote card the state always comes with its age: “In sync · Fetched 2 hours ago”, or “Never fetched”. The time is when git last wrote FETCH_HEAD, so a fetch from your terminal, your editor or Pip counts, even one that brought nothing new. In sync means in sync with what origin had at that moment. git clone does not write that file, so a fresh clone reads “Never fetched” until its first fetch or pull.
When there is no count#
Pip counts commits from git's commit-graph, a file git keeps to speed up its own history walks, and both commits have to be in it. git writes the graph during git gc and git maintenance, not after every commit or fetch, so commits that have just arrived are often missing from it — not synced straight after a fetch is normal. There is no count in a shallow clone, under grafts or replace refs, when the graph is over 16 MiB, or when counting would walk more than 10,000 commits. To get numbers now, write the graph yourself, in the repository:
git commit-graph write --reachableTo keep it current after every fetch that downloads something — yours, your editor's or Pip's — set git's own fetch.writeCommitGraph to true. Either way, git writes the file and Pip only reads it. The notification for falling further behind depends on it too.
Running a fetch#
Fetch sits on the Git tab's Remote card. With a server's screen open on the Git tab, F does the same; in Quick actions (Q) a server's entry offers Fetch — type fetch and part of its name — which opens that server's Git tab and runs it there. All three need a remote named origin, git installed, and a server running directly on this computer. Each runs one command, at the top of the server's working tree:
git -c core.askPass= -c credential.interactive=false -c gc.auto=0 -c maintenance.auto=false -c fetch.showForcedUpdates=false fetch --quiet --no-prune --no-prune-tags --no-recurse-submodules origin- Origin, and only origin. Other remotes are left alone, so a branch that tracks one of them is not brought up to date. Submodules are not fetched either; a server running inside a submodule has its own row, and its own Fetch.
- Nothing deleted. Pruning of branches and tags is off whatever
fetch.prune,fetch.pruneTagsorremote.origin.prunesay, so the fetch only downloads. git's automatic gc and maintenance do not run after it. - No prompts. git, Git Credential Manager and ssh are all told not to ask. Your own credential helper or ssh agent supplies what it already holds, as it does in a terminal; when something is missing, the fetch fails with git's reason rather than waiting on a password nobody can see. A key with a passphrase needs to be loaded in your ssh agent — and when your
GIT_SSH_COMMANDruns OpenSSH, Pip adds-o BatchMode=yesto it. - What changes. Like any
git fetch, it updates origin's remote-tracking branches andFETCH_HEAD, and stores the objects behind them. Pip never pulls, pushes, prunes, commits, checks out or switches branches, so your branches, index and working tree are untouched. Fetch is the only part of Pip's git features that uses the network, apart from History in a partial clone on an older git — see partial clones.
What you see#
While git runs, the button spins and the card's state line adds “Fetching…”. A fetch of the same repository started anywhere else — another server's row, another worktree, the schedule — shows here too, and fetches of one repository never overlap: a Fetch you ask for meanwhile waits for the one already running and shares its result. Then one of these:
- Fetched just now
- Success. The age on the card resets and the sync word follows; there is no other message.
- Could not fetch
- “Could not fetch: …” under the buttons, ending with the line of git's or ssh's own output that explains it — an unknown host, a rejected key, a repository git refuses because someone else owns it. Any credentials in a URL are cut out of it. Fix it as you would in a terminal; the sentence stays until a later fetch, Pip's or yours, replaces it.
- Fetch gave up
- “Fetch gave up after 5m. Run git fetch yourself once to check.” A fetch you start is stopped after five minutes, and a scheduled one after two. Running
git fetchin a terminal shows what it was waiting on. - git left a lock
- “git left … behind. Remove it before the next fetch.” A fetch stopped part-way can leave a
.lockfile —packed-refs.lock, say — that blocks every later fetch, Pip's and yours. Pip looks straight after and names the full path. Delete it once no other git command is running in that repository. - Install git
- “Install git to fetch from here.” — on a Mac, “Install the Xcode Command Line Tools to fetch from here.” — in place of the button, when git is not on your PATH. macOS's
/usr/bin/gitwithout the developer tools behind it counts as missing. Once git is installed the button comes back without restarting Pip. - git did not answer
- “git is installed but did not answer: …” in place of the button: git was found, but
git --versionfailed. Run that in a terminal to see why.
Fetching every 15 minutes#
Turn on Fetch repositories with a running server every 15 minutes in Settings → Git, under Fetching, and Pip fetches for you with the same command and a two-minute limit. It is off by default. The first round comes within a minute of switching it on, then one every 15 minutes while Pip is running, whether or not its window is open.
- Which repositories. Those behind servers running directly on this computer that have an
origin— not WSL or container rows. Each is fetched once a round, however many servers or worktrees use it. - One at a time. Repositories go one after another. One already fetching is skipped, and so is one Pip fetched in the last five minutes — by your click or the previous round.
- No notification. Results land on each Remote card as if you had clicked Fetch, failures included, and the Git row in Settings adds “Fetching every 15 min” to its summary. A behind notification can still follow a fetch that moved origin.
- Nothing without git. When git is missing, a round fetches nothing, and the next round tries again.
Pull requests and the web page#
Open pull request on the Remote card — Open merge request when origin is on GitLab — opens the host's new pull request page for the checked-out branch in your default browser, aimed at origin's default branch when your clone has recorded one. Pip only builds the address from origin's URL: no account, no token, and nothing sent to the host. You finish the request in the browser, where you are already signed in. It knows github.com, gitlab.com (nested groups included), bitbucket.org and Azure DevOps, on dev.azure.com or *.visualstudio.com; a self-hosted server gets no button. Quick actions offers it wherever the card does. When the button is missing or has a note, the card says why:
- Not seen on origin
- “Pip hasn't seen feature/x on origin yet — push it, or fetch.” The button stays: this is what your clone knows, not what origin has. A branch that pushes to another remote is not told this.
- Detached HEAD
- “Check out a branch to open a pull request.” Nothing is said while a rebase or bisect holds HEAD detached on purpose.
- No commits yet
- “Make a first commit to open a pull request.”
- Default branch
- “This is origin's default branch, so there's nothing to request.”
- No origin
- The card says “No origin configured”, and neither Fetch nor a pull request button appears.
Click origin's URL on the card — its tooltip says Open on the web — to open the repository's own page. Pip turns an http, https, ssh, git or scp-style remote into an https address, so git@github.com:me/app.git opens https://github.com/me/app, and credentials in the URL are dropped. Quick actions and the Repositories list offer the same. A local path or file:// remote has no web page, and Pip says “Couldn't open …: This remote has no web page.”
WSL and container rows#
A server in WSL or a container — or a Windows process serving from a \\wsl.localhost share — keeps its repository where Pip will not reach on demand: a read over the WSL share can wake a distro you stopped, and a container's folder may not be on this computer at all. Its Git tab shows what the background scan read — the branch, where it stands, origin's URL — and says where to do the rest.
- Fetch
- “Fetch from inside WSL.” or “Fetch from inside the container.” in place of the button. F and Quick actions offer no fetch there, and the 15-minute schedule passes these rows by.
- Pull request
- Still offered, from what the scan read: the page opens without a target branch, so the host picks its default, and the card never says the branch has not been seen on origin.
- Open on the web
- Works as usual — it needs only origin's URL.
- Notifications
- None. Pip watches only repositories on this computer, which is also why the tray never says
upstream gonefor a WSL row.
Did this page not answer it? Tell us what you were looking for — that is how Pip's documentation gets written.