Fetch, pull and push
Download what others have done, bring it into your branch, and upload your own commits.
What the three buttons do
A remote is a copy of the repository on a server. Your local repository and the remote do not sync by themselves. Three actions move commits between them:
| Action | What it does |
|---|---|
| Fetch | Downloads new commits and branches from all remotes. It does not change your files or your branches. It also forgets remote branches that were deleted on the server. |
| Pull | Fetches, then brings the new commits into your current branch. |
| Push | Uploads the commits on your current branch to the remote. |
The buttons are in the header, to the right of the repository path.
Fetch
Select the fetch button, or press F5. Its tooltip reads Fetch all remotes (F5).
After a fetch, the graph shows where the remote branches are, and the header shows how far your branch is ahead of or behind its upstream.
Pull
Select the pull button. When your branch is behind, the tooltip shows by how much, for example Pull (behind 3).
Pull runs git pull, so it follows your Git settings for whether to merge or rebase. If your local commits and the incoming ones touch the same lines, you get conflicts to resolve. See Resolve conflicts.
Push
Select the push button. When you have commits to upload, the tooltip shows the count, for example Push (ahead 2).
The first time you push a new branch it has no upstream yet. BranchPilot sets one for you: the task is labelled Push (set upstream), and from then on the branch tracks the remote branch of the same name.
Watch progress and cancel
Fetch, pull and push run as tasks in a strip in the window. Each task shows its name and the latest line of real Git output as it arrives.
- Select Cancel on a running task to stop it.
- Select Dismiss to clear a finished task.
- Select a failed task to open a dialog with the end of Git's error output.
When a task waits for sign-in
BranchPilot never asks for a password. It relies on what Git already uses: a credential helper for HTTPS remotes, or ssh-agent for SSH remotes. If neither can answer, the task fails and shows the hint Waiting on authentication? Run this once in a terminal, then retry.
Do what it says: run the same command (git fetch, git pull or git push) once in a terminal inside the repository, and sign in there. Once your credential helper has stored the sign-in, or your SSH key is loaded in ssh-agent, retry in BranchPilot.
If you installed the snap and use SSH remotes, also run sudo snap connect branchpilot:ssh-keys once. See Install.
Force push
A normal push is refused when the remote branch has commits yours does not. After you rewrite commits you already pushed (by amending or rebasing), the histories differ on purpose, and you need a force push to replace the remote branch with yours.
Select the small arrow next to the push button (More push options).
Choose Force push (with lease)….
The Force push with lease dialog says: "This rewrites the remote branch. Type the branch name to confirm." Type the branch name exactly.
Select Force push.
"With lease" is a safety check: Git only overwrites the remote branch if it is still where your last fetch saw it. If someone pushed in the meantime, the force push is refused instead of deleting their work.
DANGER
A force push replaces the branch on the server. Commits that exist only there are removed from the branch, and anyone who already pulled the old commits has to repair their copy. Do not force push a shared branch such as main unless your team has agreed to it.
Push a tag
Tags are not uploaded by a normal push. In the Tags section of the sidebar, open the menu on a tag (Tag actions) and choose Push to remote.
Refresh
BranchPilot watches the repository folder and updates by itself when files change, a commit lands or a branch moves. If something looks out of date, select Refresh everything at the end of the header.