Git Troubleshooting

This guide helps you fix common git problems. For the daily workflow, see the Git Workflow Guide. If you cannot solve your problem, ask the issue's lead on the GitHub issue or on Slack.

Troubleshooting

If you do not understand an error, do not guess. Ask the issue's lead on the GitHub issue or on Slack. The lead can also fix your remote branch directly if necessary.

Tips for what to do in common situations, such as:

• Rebase Fails with Merge Conflict Error
• PR Includes Unrelated Commits
• Commits Include Unrelated Changes
• Failing the Generate POT Check
• Could Not Read From Remote Repository
• Manual Merge Conflict Resolution

Rebase Fails With Merge Conflict Error

Sometimes when you try to rebase your branch after updating your master branch, you'll get an error message like this:

Auto-merging openlibrary/templates/about/team.json
CONFLICT (content): Merge conflict in openlibrary/templates/about/team.json
error: could not apply 447122b8d... Switch out personal URL for team page
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".

There is a fairly simple way to resolve a conflict like this in VSCode's editor, but you first want to make 100% sure that you're dealing with an actual merge conflict, as this error can sometimes happen as a result of accidental commits on one of your branches or another out-of-date branch issue.

If this is the case, using the merge conflict resolution tools in VSCode or GitHub will only create more problems, so before starting a manual resolution, you'll want to run:

git rebase --abort

And then check in with your issue's lead to determine what steps to follow and/ or double-check to ensure you're dealing with an actual merge conflict by:

1. Following the steps in Working on Your Branch to confirm that your master is up to date and not "ahead" by any commits before trying to rebase again.
2. Ensuring that your PR does not include any unrelated commits, by checking the "Outgoing" commits in the VSCode Source Control tab and/or the "Commits" tab on your PR on GitHub. If you find any, follow the steps in PR Includes Unrelated Commits.
3. Ensuring that your commits don't include any unrelated changes, by checking the "Outgoing" changes in the VSCode Source Control tab and/or the "Files changed" tab on your PR on GitHub. If you find any, follow the steps in Commits Include Unrelated Changes.
4. Ensuring that you aren't getting this conflict because the pre-commit CI made some commits on your behalf. You'll see these in the "Commits" section on GitHub, and you'll want to pull them into your branch with git pull upstream name-of-your-branch before trying to rebase. After this, you'll need to run a git push -f origin HEAD to keep everything up to date.

If you've tried each of the above steps, and you're still getting the merge conflict error, you can now either contact your issue's lead for help moving forward, or begin to resolve it manually.

PR Includes Unrelated Commits

Sometimes if you have a look at the outgoing changes in the VSCode Source Control tab or the "Commits" in your submitted PR, you'll notice that there are other changes included along with yours that either a) you made but didn't intend to include in this PR, or b) were made by other people.

The most common reason this would happen is that you pulled in the upstream changes but forgot to push to your remote branch as well. So before proceeding, you'll want to confirm that you've pushed everything up:

git switch master
git pull --ff-only upstream master
git push origin master
git switch your-branch
git push -f origin HEAD

If you can see that the extra commits are now gone, you're good to go. If not, this means that you will need to manually remove the unneeded commits from your branch, like so:

1. Switch to the correct branch and run the following command. If using VSCode, it's recommended that you do this in the built-in terminal to ensure that the next few steps also happen in VSCode.

git rebase -i master

This will open a text editor that you can use to select which commits you actually want included in your PR, i.e.:

pick eb8ab51 [Your commit message]
pick a18d382 [Someone else's commit you don't want]
pick 76b9883 [Your commit message]

# Rebase ef7d551..23961be onto ef7d551 (7 commands)

To remove an unwanted commit, simply switch the text from pick to drop in the text editor and close the window. Once this is done, you can double-check that the unwanted commits are now gone, and force-push your changes:

git push -f origin HEAD

Note: If the text editor opens in something other than VSCode and you're unsure how to close it, and/or you'd like to try some more advanced commit manipulation methods, see Commit History Manipulation to learn more.

Commits Include Unrelated Changes

Sometimes if you have a look at the outgoing changes in the VSCode Source Control tab or the "Files changed" in your submitted PR, you'll notice that there are a number of changes made and/or files changed that you didn't intend to include in the PR.

If you look at the commit history ("Commits" tab on GitHub) and can confirm that those changes each come from someone else's commit or a separate commit of yours that was accidentally included, you can follow the steps in PR Includes Unrelated Commits.

But if you can see that the unrelated changes are actually included in commits you do want to keep, you can do the following:

1. Ensure your master branch is up to date:

git switch master
git pull --ff-only upstream master
git push origin master
git switch your-branch

1. "Soft" reset as many commits as you need, i.e.:

git reset --soft HEAD~[number of commits to undo]

This will effectively undo your commit (or commits) and return the changes to staging. You can then undo any changes you don't want included, i.e.:

In the VSCode Source Control tab:

• Hover over the changed file you want to undo changes to
• Hit the minus sign to remove it from staging
• Hit the reverse symbol to undo the changes

Or, in the terminal:

# Remove unwanted file from staging -- or use a . instead of filename to unstage all
git restore --staged path/to/your/file

# Undo changes to selected file
git checkout -- path/to/your/file

You can then re-commit your desired changes, and push your changes back up:

# Add any files you want to commit back to staging if needed
git add file-to-include
git commit -m "Your original commit message"

# Force push to overwrite the remote version
git push -f origin HEAD

Failing the Generate POT check

If your commit involves adding, removing or altering text that will be visible to the user and is properly internationalized, an update of the translation template file will be automatically bundled in with your changes via pre-commit.

To learn more, see Pre-Commit Guide.

Could Not Read from Remote Repository

It may happen that when you try to pull in the upstream version of the repository, you'll get the following error:

fatal: 'upstream' does not appear to be a git repository
fatal: Could not read from remote repository

Please make sure you have the correct access rights and the repository exists.

This just means that your branch has accidentally gotten disconnected from the OL master branch. All you need to do to fix it is add upstream repo to list of remotes and double-check that it worked.

You can then safely try pulling again to keep everything up to date.

Manual Merge Conflict Resolution

Note: Manual merge conflict resolution can get a little tricky, so if at any time you want to stop and ask for input from your issue's lead, you can simply run git rebase --abort to return everything to its pre-rebase state. The lead will also be able to edit your branch for you on GitHub to resolve the conflict if necessary.

A merge conflict happens when your changes conflict with other changes that have just been added to the repository.

For instance if you changed:

<div>Hello world!</div>

to

<p>Hello world!</p>

And then you pulled in someone else's change from upstream that had for instance changed Hello world! to Hi world!, you would be faced with a merge conflict, because git would not know whether to make the line <p>Hi world!</p> (both changes combined) or treat your version (<p>Hello world!</p>) or their version (<div>Hi World!</div>) as authoritative.

Similarly, if someone else had made conflicting changes but you hadn't rebased to include them before submitting your PR, GitHub would add a warning to the PR that your branch could not be merged until conflicts were resolved.

Note: You'll only want to do this if you're 100% sure you're dealing with a real merge conflict, i.e. you can see a recent commit to the codebase that would conflict with one of your commits. To double-check and confirm you've got a true merge conflict, see Rebase Fails with Merge Conflict Error.

Once you've ensured you do have a merge conflict, you can start the rebase again in VSCode by switching to your branch and running git rebase master and use its built-in merge editor to resolve the conflict(s):

Conflicting changes will be highlighted, and you'll have three main options:

1. "Accept Current Change" - Line becomes <p>Hello world!</p>, your commit now overwrites theirs, and includes changing "Hi world!" back to "Hello world!"
2. "Accept Incoming" - Line becomes <div>Hi world!</div>, you undo all your own changes to the line and keep it as they have it
3. Custom/Combination --

• To use a combination of the two changes, i.e. <p>Hi world!</p>, select "Resolve in Merge Editor" which will open this view:
• Either select "Accept Combination" or edit the result text directly to match the desired combination
• Select "Complete Merge"
• You'll see your resulting change ready to go in the source control tab, with your previous commit message already filled in, and you can just hit "Continue" to re-commit and finish up

Once you're done rebasing, you'll want to force-push your changes up using:

git push -f origin HEAD

And then the merge conflict resolution is complete.

Advanced Git Operations

Commit History Manipulation

WARNING

An incorrect interactive rebase can change or delete commits. Make sure you understand each command before you use it.

Sometimes you'll want to rearrange/reword/combine commits to keep the history neat. To do this, on your branch, run:

git rebase -i master

Info
The -i is for interactive. The command is also specified often as something like git rebase -i HEAD~2. HEAD refers to the current, latest commit in your branch; ~2 goes back 2 in the history, so you'll be manipulating the last 2 commits. git rebase -i master lets you manipulate all the commits on your branch.

Info
By default, git will open up an editor in your terminal (likely vim). If you would rather use VS Code, run git config --global core.editor "code" once, and then git will always use VS Code when prompting for a rebase, or a commit message.
If you happen to find yourself stuck in vim and don't know how to get out, press ggdG:wq (in order: g for "go to", g for "top of file", d for delete, G for "to bottom of file". So ggdG is for "go to the top of the file, and delete everything". This is how you cancel git rebase -i. Then: : for "enter command-line mode", w for "save", q for "quit". So wq is "save and quit". If you're interested in learning more about vim, see https://vim.fandom.com/wiki/Tutorial

This will open a text editor, and let you edit all the commits that your branch has. It will look something like this:

pick eb8ab51 Made footer's HTML translatable
pick a18d382 Fixed some typos
pick 76b9883 Made footer's HTML translatable: added the missing translatable strings
pick 73c78b7 Fix git hash version i18n
pick 377e121 Added a missing translatable string
pick caf9507 Reverted unrelated changes to the PR
pick 23961be Clean up trailing whitespace

# Rebase ef7d551..23961be onto ef7d551 (7 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.

If you decide you want to cancel the rebase, delete everything, and then save. That tells git to do nothing.

To continue with the rebase, save the file. git will then replay all the instructions/commits in that file. If there's a conflict, it will pause to let you fix them. See Manual Merge Conflict Resolution.