Unboxing fork improvements
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.
Recent fork improvements
The following fork improvements were released in recent months.
Sync an out of date branch of a fork from the web
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.
Use the API to sync a fork with its parent repository
Forked repositories can now be synced with their upstream parent repository using the sync a fork branch with the upstream repository API.
Set via API whether a repository allows forking
You can now set whether a repository allows forking when creating or updating it using either the REST or GraphQL API.
You can now name your fork when creating it
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.
Fork a repository to the same organization as its parent
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.
Fork internal repositories to enterprise organizations
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.
Enterprise and organization owners can limit where forks can be created
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.
The repository fork button now displays existing forks
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.
You can now fork a repository and copy only the default branch
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.
Improved UI for syncing a fork
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.
Better forks, forever
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.