Change requests

Collaborate on content edits through change requests

A change request is a copy of your main content. It's based on the concept of branching, and feels familiar to anyone who uses pull requests in GitHub or merge requests in GitLab.

In a change request, you can edit, update, and delete content, request reviews on your changes, then merge them back into your main version.

To browse and manage open change requests across your site, see the Change requests screen.

A GitBook screenshot showing the change requests panel
Edit your content through change requests.

Review changes in diff view

Open the Changes tab to review edits in a change request. You can review all pages in context, or focus on changed pages only.

The change request’s header shows how much it changes, Git-style: the number of additions, modifications, and deletions, such as +12 Δ3 −6, with a colored bar showing the share of each. Reviewers can tell a typo fix from a full rewrite before they open the changes.

While you review, the sidebar tracks your progress as N / M viewed. Tick Viewed on each page once you’ve reviewed it.

At the bottom of the editor, the floating diff navigator lets you jump between changed blocks, continue to the next page with diffs, and finish the review from the last change with the available review actions.

By default, changes are shown in a "split-view". The left side shows the 'before' version of the page, and the right side shows the 'after' version. If you prefer to view changes inline in a single-column layout, click the diff-mode button at the top-right of the Table of contents panel.

Create and merge a change request

1

Open a change request

To edit content, open a change request. You can open one in a few ways:

  • Click Edit in the top right corner of a section.

  • Ask GitBook Agent to create one on your behalf.

  • GitBook Agent may create one automatically when it detects a documentation gap.

If you open one manually, GitBook creates the change request and opens it in the editor.

2

Make your changes

Edit content directly in the editor, or work with GitBook Agent.

Review your changes before you move on. You can keep editing until you're ready to request a review.

3

Request a review

Open the Overview tab, then tag one or more reviewers.

Reviewers can approve your changes, leave comments, or request more edits. If you don't tag anyone, everyone with reviewer permissions in the section is notified. If the section has no reviewers, editors and admins are notified instead.

If someone requests changes, update the change request before you merge it. You can also ask GitBook Agent to review the change request.

4

Merge

Once the change request is approved, open the Overview tab and click Merge.

GitBook applies the changes to your live docs immediately. If your section uses merge rules, GitBook checks them before merging.

Merging can't be undone. To revert or adjust content, open a new change request.

Working with change requests

Last updated

Was this helpful?

Powered by GitBook