Troubleshooting and FAQ
Symptoms and questions that come up most, with the cause and the fix.
Opening repositories
"Not a git repository"
The folder you chose is not inside a Git repository. Choose a folder that contains a .git folder, or any folder below it. To turn a plain folder into a repository, run git init in it from a terminal.
Can BranchPilot clone or create a repository?
No. Version 1.0.0 opens existing repositories. Clone with git clone or create with git init in a terminal, then open the folder.
How do I remove a repository from the recent list?
On the welcome screen, select Remove from recent on its row. This only removes the entry; the repository stays on disk.
Sign-in and remotes
Fetch, pull or push fails with "Waiting on authentication?"
BranchPilot never shows a password prompt. Git has to be able to sign in by itself, through a credential helper (HTTPS) or ssh-agent (SSH). Run the same command once in a terminal inside the repository, for example git fetch, and sign in there. Then retry in BranchPilot.
SSH remotes fail with "Permission denied" in the snap
The snap cannot read your SSH keys until you allow it:
sudo snap connect branchpilot:ssh-keysDoes BranchPilot store my password or token?
No. It never sees them. Sign-in is handled by Git's credential helpers and ssh-agent, the same as in a terminal.
Push is rejected
The remote branch has commits you do not have. Pull first, resolve any conflicts, then push. If you rewrote commits on purpose (amend or rebase), read about force push before using it.
Committing
The Commit button is disabled
It needs a non-empty Commit subject and at least one staged file. With Amend turned on, a subject is enough.
The commit fails and Git asks who I am
Git has no name and email for you. Set them in a terminal:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"In the snap, the global configuration file is not visible to the app. Run the same two commands without --global inside each repository. See Install.
Pressing Space does not stage the file
Space works on the file whose diff is open, and only when no text field has focus. Select the file in the changes panel first, and click outside the commit box.
A file shows "Binary file" or "No textual changes"
Git cannot show a line-by-line diff for binary files such as images. No textual changes means the diff has no changed lines to show, for example when only the file's permissions changed. You can still stage the whole file.
Branches, merges and rebases
Continue is disabled
At least one file is still listed under Conflicted. Resolve each one with Take ours, Take theirs or Mark resolved. See Resolve conflicts.
"Interactive rebase onto this commit…" is greyed out
Either you right-clicked the commit you are currently on, or you are not on a branch (detached HEAD). Check out a branch and pick an earlier commit.
"Reset … to here…" is greyed out
Reset moves a branch, and you are not on one. Check out a branch first.
I cannot delete or merge a branch
Delete… and Merge into current… are unavailable for the branch you are on. Check out another branch first.
A branch shows "gone"
The remote branch it tracked was deleted on the server, usually after a pull request was merged. Your local branch is unaffected. Delete it if you no longer need it.
I started a merge or rebase by mistake
Select Abort in the banner. The branch and working tree return to how they were before the operation.
How do I undo a commit?
- Already pushed: right-click it and choose Revert this commit. This adds a new commit that undoes it.
- Not pushed, and it is the latest: right-click the commit before it and choose Reset … to here… with Soft or Mixed. Your changes stay in your files.
Both are described in Stashes, tags and other tools.
The app
The window looks out of date
BranchPilot watches the repository folder and refreshes by itself. If it missed something, select Refresh everything in the header.
Is there a version for Windows or macOS?
No. BranchPilot is a Linux desktop app.
Does it include its own Git?
The .deb and PPA packages use the git installed on your system, version 2.28 or newer. The snap is sandboxed and cannot run your system's git, so it carries its own copy inside the snap.
Where do I report a bug or ask for a feature?
Open an issue on the BranchPilot issues page. Include your BranchPilot version, your distribution, how you installed the app, and the Git error text if there is one.