Branches

With branches, you can continue to edit as you always have! Branches are an optional workflow that offer flexibility in your writing process. Writers use branches to:

• Make changes and review them in a preview environment before they’re live.
• Send changes to teammates for review.
• Make changes across multiple pages.

Creating a Branch

There are three ways to create a branch:

1. From the Branches page.
2. From the versions and branches menu in the sidebar. Once there, you can create new branches from a version by typing in the branch you want to create.
3. While editing an individual guide, endpoint, etc., you can Save to Branch.
4. If you’re syncing with GitHub , branches created in GitHub will show up in ReadMe. And branches created in the ReadMe UI will automatically show up in GitHub!

Once your branch is created, you can start writing! Changes will not be live until you merge your branch into a public version.

There are no time limit or expiration on branches. Any admin on your team can view, edit, merge, and delete any branch.

Reviewing Changes

When editing a branch, you can access the Review tab to compare the changes made in your branch.

Customers with the Review feature can also mark branches as ready for review, which adds a badge in the versions and branches menu, and starts the AI Linter. Users can bypass the merge requirements by checking the "Merge without requirements met" box to enable the Merge button. Learn more about reviews.

Merging Changes

Once you’re ready for the changes to go live, you can merge from the branch menu:

On merge, a check will be run to ensure there are no merge conflicts. If there are conflicts that must be resolved, we recommend resolving the conflicts from GitHub. If your project does not sync with GitHub, you can to ignore the conflict and forcefully merge their changes—with preference to the changes in the branch.

Once merged, your branches are not deleted so you can review the changes before deleting them.

Restricting Merge to Admins

Enterprise Customers can restrict merge access per project to Only Admins or Admins & Editors. The settings can be found on the Enterprise Dashboard’s Project Page. Open Settings > Enterprise Name (at the bottom) > Projects.

It's important to note that this is a ReadMe permission, not a GitHub branch protection rule. If you've enabled bi-directional sync and an Editor chooses to merge a branch in GitHub, the merge would succeed on GitHub's side because GitHub doesn’t know about ReadMe’s role restrictions. The sync process would then push the merged state back to ReadMe, effectively bypassing the restriction.

Sharing Branches

Every branch has a shareable URL that allows access to your branch for both logged in and external users. From the Branches page, select the three dots next to your branch name and copy the Shareable URL. You can also find the shareable URL on the branch Review page.

Enterprise teams can disable external sharing per-project on the Projects page in the Enterprise Dashboard.

Syncing with GitHub

You do not have to sync with GitHub to use branches.

When creating branches from GitHub, their name has to be formatted to include their version: {version}_{branch}. Examples:

v2.0_rewrite-getting-started
v2.0_add-new-feature
v2.0_fix-typo

Access & Permissions

ReadMe and GitHub permissions are independent. Users with access to your GitHub project’s branches will have access to any content changes. In order for users to view content changes made in branches via GitHub, they will need a ReadMe account with access to your project’s branch.

Handling Conflicts

When merging from GitHub, the user can resolve conflicts via the GitHub editor or the merge tool of their choice locally before pushing.

When merging from ReadMe, the changes you see when previewing will always match what goes lives when merging. Conflicting changes from GitHub will not appear.

FAQ