Here at GitBook, we’ve always believed that a Git-like workflow is at the core of a collaborative process. That’s why we’ve had change requests and diffs in our app for so long. But what is a diff? How do they work in a Git workflow? And what makes them such a powerful collaborative tool?

To answer these questions, here’s a complete guide to diffs — what they are, how they work in GitBook, and why they’re a game changer when it comes to working with your team.

What is a diff?

‘Diff’ is short for ‘difference’, and it describes the way that a tool shows the changes (or differences) between two or more versions of the same file or codebase. Diffs were originally developed in the 1970s as part of the Unix operating system, and today they are used widely in a variety of tools including the likes of GitHub, GitLab and GitBook. In those tools, they’re a key part of what is often called a ‘Git workflow’ — more on that in a moment.

How do diffs work in Git?

Diffs are a simple, visual way of seeing the differences between two files — or two versions of the same file. When you compare the two, additions to the file are highlighted with a green +, and anything that’s been removed or deleted has a red -. Other changes, such as an image being updated, will be marked with a blue dot •.

In Git workflows, the diff view will typically show the changes that you or someone else has made to a document, comparing it to the main version. In these Git environments, you cannot directly edit the ‘main’ files themselves. Instead, you create a ‘branch’ — a copy of the main file at that moment in time — and then make edits within that branch.

When you or someone else wants to check over your changes, you can compare this branch to the main version of the file — with diffs quickly and easily showing them what you’ve added, removed or changed. Once everyone is happy, you can ‘merge’ that branch in to the main version of the file, and update it with all your changes.

Why does GitBook have diffs, and how do they work?

GitBook is a powerful knowledge-sharing platform designed to make writing technical documentation and sharing technical information with your team easier. And when we first set out to build it, we were inspired by the likes of GitHub and GitLab. The branch-based workflow not only meant teams could avoid accidentally publishing something incorrect without checks. It also encouraged collaboration — which is essential when you want everyone to contribute their own technical knowledge to your central knowledge hub.

That’s why, in GitBook, you can’t edit a published page live. Instead, you can create a ‘change request’ — which creates a new branch — and then make edits within that branch. You can either make all your changes in one go, or make a few edits, then leave your change request and return to it later.

Once you’re happy with your changes, you can submit your changes for a review from someone in your team. They can jump straight into your change request, and use the diff view toggle to instantly see which pages you’ve made changes in. On individual pages, the diff view will also show the specific blocks that you’ve added, edited or removed.

What makes diff view so useful in GitBook?

Diff view makes reviewing changes super simple, as you can quickly see the sections someone has edited and focus purely on them, rather than having to check everything on the page to make sure it’s all correct. It’s also great if someone deletes something accidentally — without knowing it was gone, you may not notice that it was missing during a review.

Combine this with feedback through comments and you’ll see the true power of change requests. By involving others in your workflow, you can expand the knowledge within your pages, making your knowledge base or technical documentation documentation better than ever.

At GitBook we always want to give you the best experience when sharing knowledge and publishing technical documentation alongside your team. We believe a change request workflow is at the core of that collaborative process — we think it’s the best way to work. And diff view is a big part of that.

We’re always working to make things better

With all that in mind, we wanted to mention a couple of recent improvements we made to change requests — with more coming soon.

A few weeks ago we improved notifications and comments for change requests, and updated out diff view to offer more useful information at a glance. And soon, we’ll give you more information about a change request when you open it, including who created it, who edited it last, and a quicker way to check the history of the change request.

We have even more improvements in the pipeline, too — but we’ll save that for a future post.

That’s it! Now you know what a diff is, why they’re so helpful in the Git workflow, and how they help your whole team contribute and collaborate more effectively.

→ Find out more about change requests

→ Read the documentation