Text of docs.openlibrary.org › developers › tools › git.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Git | Open Library Docs

Skip to content Git ​ This guide is for contributors working on Open Library pull requests. It covers the standard day-to-day workflow first, then troubleshooting and advanced git operations. Prerequisites: complete Quick Start and ensure your local Open Library repository is set up. Git Workflow (Start Here) ​ Quick Workflow Checklist ​ Sync master with upstream using Canonical Sync Commands . Create or switch to your working branch.

Make and test your changes. Push your branch and open a pull request. If your PR needs updates, repeat from step 1 and rebase. Detailed Workflow ​ Fork the Open Library repository ​ Log in to GitHub. Go to https://github.com/internetarchive/openlibrary and click the Fork button in the upper right corner: Clone the forked repository on to your local computer ​ This creates a local copy of your own fork of the Open Library repository, in a directory called openlibrary .

Your fork on the GitHub servers is a remote called origin . By default, you are looking at the master branch. Make sure you git clone openlibrary using ssh instead of https as git submodules (e.g. infogami and acs ) may not fetch correctly otherwise. sh git clone git@github.com:USERNAME/openlibrary.git Permission denied while cloning ​ If you have not added your public SSH key to GitHub you may see: sh git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.

To fix this, first generate a new SSH key if you have not already done so, and then add the SSH key to your GitHub account . Modifying a repository that was incorrectly cloned using https (or is missing the infogami module) ​ You can modify an existing openlibrary repository that was inadvertently cloned with https by running: sh git remote rm origin git remote add origin git@github.com:USERNAME/openlibrary.git git submodule init ; git submodule sync ; git submodule update Fix line endings, symlinks and git submodules (only for Windows users not using a Linux VM) ​ The project files need LF line endings because they are used in a Linux Docker container, even if run from Windows.

Additionally, symlinks don't clone properly, and this creates issues for the git submodules. For more on git and line endings, see Configuring Git to handle line endings . Note: if you get permission issues while executing these commands please run git the bash shell as an Administrator. sh # Get in the project root directory cd openlibrary # Configure Git to keep LF line endings on checkout even on Windows. git config core.autocrlf input # Enable symlinks git config core.symlinks true # Build submodules git submodule init ; git submodule sync ; git submodule update # Stage indexed files for removal so git reset updates them git rm --cached -r . # Don't forget the "." # Reset the repo (removes any changes you've made to files and is likely to give an error if not administrator) git reset --hard # You will almost certainly need to use git-bash as administrator for this.

Add 'upstream' repo to list of remotes ​ sh cd openlibrary git remote add upstream https://github.com/internetarchive/openlibrary.git Verify the new remote named 'upstream' ​ sh git remote -v # origin git@github.com:USERNAME/openlibrary.git (fetch) # origin git@github.com:USERNAME/openlibrary.git (push) # upstream https://github.com/internetarchive/openlibrary.git (fetch) # upstream https://github.com/internetarchive/openlibrary.git (push) Note that origin is git@ .

If it is not, see Fork the Open Library repository . Working on Your Branch ​ Canonical Sync Commands ​ Because new commits are frequently merged into the Open Library repository, it's important to make sure that the branch you're working on is up to date with the upstream master version. Before creating a new branch and each time you start work on an existing branch, you should run the following commands to make sure your master branch is up to date: sh git switch master git pull --ff-only upstream master git push origin master Note: When running pull --ff-only , you may encounter the error fatal: Not possible to fast-forward .

If this occurs, refer to the Out-of-Sync Branches section for instructions on resolving this issue. You can then create a new branch for your issue: sh git switch -c 1234/fix/fix-the-thing Or, if you are returning to work on a previously created branch, rebase* with master: sh git switch existing-branch-name git rebase master * Note: Rebasing is the equivalent of "lifting" all the commits in your branch, and placing them on top of the latest master.

It effectively changes the base of your branch/commits. If you encounter any errors in the rebase process, see the troubleshooting guide . You can confirm everything is up to date by running git status and/or visiting your remote master branch at github.com/your-username/openlibrary , where you should see the following: If everything looks good, you can continue following the steps in Making Changes and Creating a Pull Request to commit, test and submit your changes.

If not, read on! Out-of-Sync Branches ​ Your master or working branch may get out-of-sync. In general, do not use VSCODE or GITHUB MERGE to resolve merge conflicts. Here are some commands to run for common out-of-sync situations: (Note: you check the status of your branch by running git status or going to github.com/your-username/openlibrary ) Local master is behind upstream master sh git switch master git pull --ff-only upstream master git push origin master Local master is both behind and ahead of upstream master sh git switch master git reset --hard HEAD~[the number of commits you are ahead by] git pull --ff-only upstream master git push -f origin master WARNING git reset --hard deletes commits permanently.

You cannot recover these commits. Run this command only on the master branch, never on a working branch. Your local master branch must match upstream master . If you accidentally made commits on master , remove these commits with the commands above. Then pull from upstream again. Working branch is behind upstream master (it will be ahead if you've made local changes): sh git switch master git pull --ff-only upstream master git push origin master git switch your-branch-name git rebase master If rebasing your branch fails or provokes merge conflicts, see Troubleshooting .

When you're done working and try to push your branch with git push origin HEAD , you may encounter the following error: This usually means that, as a result of the rebase, you'll need to force push* your updates: sh git push -f origin HEAD * Note: While regular pushing just adds new commits to the remote branch, force pushing replaces the commits on the remote branch with the commits on your local branch, effectively re-writing the remote commit history.

Sometimes when you perform a rebase, you will have to force push to your branch. If so, be sure to force push with care: You should only force push if working on one of your own branches. If working on a branch which other people are also pushing to, force pushing is dangerous because it can override others' work. In that case, use --force-with-lease ; this will force push only if someone else hasn't made any changes to the branch.

If none of the above solved the issue, you can consult a staff member or the issue's lead, and/or see Troubleshooting . Making Changes and Creating a Pull Request ​ 1. Make sure master is up-to-date (use Canonical Sync Commands ): For troubleshooting or to learn more, see working on your branch . 2. Create a new branch for the feature or issue you plan to work on and switch to it: sh git switch -c 1234/fix/fix-the-thing Specifying -c creates a new branch, and switch switches to it.

The typical branch name format is [issue number]/[fix/feature/refactor/docs/test/hotfix]/[short-issue-description] 3. Make changes/commit: sh git add the-file.html git commit -m "Fixed the thing" A commit message should answer three primary questions: Why is this change neces

The rest of this page is on the live site.