We’re always trying to improve the GitHub developer experience, and we love learning from developers. One theme we’ve heard a lot recently is that forks are confusing. What is a fork? How do fork permissions work? What are the security and permission implications? How do I know who has forked my repository and what commits they added?
Based on the increasing volume of queries about forks, we realized we needed to improve how forking works, and we needed to have more details in our documentation. As a result of your feedback and questions, in the last several months we released several new fork capabilities, described below. We are also publishing revised fork documentation that gives more details with clearer explanations to make fork concepts easier to understand.
The following fork improvements were released in recent months.
You can now use the web interface to synchronize an out-of-date branch of a fork with its upstream branch. If there are no merge conflicts between the branches, the fork’s branch is updated either by fast-forwarding or by merging from the upstream’s branch. If there are conflicts, you will be prompted to open a pull request to resolve them.
Forked repositories can now be synced with their upstream parent repository using the sync a fork branch with the upstream repository API.
Previously, when you forked a repository the fork name would default to the same name as the parent repository. In some cases, that wasn’t ideal because you wanted the fork to have a different name. Your only option was to rename the fork after it was created. Now, you can save time by customizing the fork name as you create it.
Previously, a repository could be forked only to a different organization or user account. Now, a repository can also be forked to the same organization as its parent, addressing situations where people are working in just one organization.
Previously, when a repository with internal visibility was forked, the fork was automatically created in the person’s personal account space and its visibility was changed to private. Now, you can fork an internal repository to an organization in the same enterprise, and the fork will retain its internal visibility.
Previously, enterprise and organization owners couldn’t restrict where repositories could be forked. That was important for them to keep confidential repositories from accidentally being forked to an exposed location. Now, enterprise and organization owners can control where their members can fork repositories. Forking can be limited to preset combinations of enterprise organizations, the same organization as the parent repository, user accounts, and everywhere.
A dropdown has been added to the “Fork” button to help you quickly find your forks of a repository. This includes forks in your personal account and in organizations that you’re a member of.
Previously, when creating a fork all branches from the parent repository were copied to the new fork repository. There are several scenarios where this is unneeded, such as contributing to open-source projects. When all branches are copied, it could result in slow repository cloning and unnecessary disk usage. With this new feature, only the default branch is copied—no other branches or tags. This may result in faster clones because only reachable objects will be pulled down.
We updated the web UI to make keeping forks in sync with their upstream repositories more intuitive. “Fetch upstream” has been renamed to “Sync fork,” which better describes the button’s behavior. If the sync causes a conflict, the web UI prompts developers to contribute their changes to the upstream repository, discard their changes, or resolve the conflict.
We aim for continuous improvement, and we want these improvements to be meaningful. The trends told us that there was a fundamental misunderstanding about forks and how they work. Forks are crucial to a lot of workflows, so it’s important to understand them correctly.
We want our fork documentation to be clear and answer the questions you have. We will continue to monitor trends in queries and iterate the fork docs as necessary. We also welcome your contributions to GitHub documentation in the github/docs repository.
We want forks to be easy to understand and use. Please let us know how we can improve forks for you.