What are stacked diffs and how do they work?

Managing code changes efficiently in large-scale projects can be challenging. Developers often need to create, review, and merge multiple interdependent changes without disrupting the workflow. This is where stacked diffs come into play, offering a structured way to handle complex changes in a clear and manageable manner.

Stacked diffs provide an alternative to the traditional way of submitting code changes as independent, unrelated pull requests or patches.

• They enable developers to organize their work into a series of dependent changes, or "diffs," stacked on top of each other.

  
  

• These changes are reviewed and merged sequentially, making it easier to reason about the logic and ensure quality.

Why Were Stacked Diffs Introduced?

As software development teams scaled, traditional workflows started showing limitations:

1. Difficulty Managing Dependencies

   Developers often faced issues when a feature or bug fix depended on another in-progress change. Merging these interdependent changes out of order could lead to broken functionality or conflicts.

   
   

2. Inefficient Code Reviews

   Reviewing a large, monolithic change is time-consuming and error prone. Reviewers struggled to understand the context, and discussions often became overwhelming.

   
   

3. Merge Conflicts

   Uncoordinated changes in the same files often led to conflicts that were tedious to resolve.

   
   

4. Lack of Clarity

   Developers and reviewers alike found it challenging to track which changes were ready for review, which depended on others, and which were blocked.

   
   

To address these challenges, the idea of stacked diffs was popularized, notably by tools like Facebook’s Phabricator and more recently adopted in workflows using GitHub or GitLab.

What Are Stacked Diffs?

At its core, a stacked diff is a series of changes, or patches, where each depends on the previous one in the stack. These changes are built sequentially, creating a clear hierarchy.

Example:

Imagine you're building a new feature in a web application. The process might involve:

1. Base Change: Add an API endpoint.

   
   

2. First Layer Diff: Implement business logic using the API.

   
   

3. Second Layer Diff: Build the frontend components for the feature.

   
   

Each diff builds on top of the previous one, making the progression logical and the review process straightforward.

Key Benefits of Stacked Diffs

1. Granular Code Reviews

   By breaking changes into smaller, dependent units, reviewers can focus on specific aspects without being overwhelmed by an entire feature's implementation.

   
   

2. Improved Collaboration

   Developers can share progress incrementally, enabling early feedback and smoother iterations.

   
   

3. Conflict Minimization

   Since diffs are organized hierarchically, conflicts are limited to specific layers, making them easier to isolate and resolve.

   
   

4. Clarity in Dependencies

   Stacked diffs make it clear which changes depend on others, helping teams coordinate better.

5. Parallel Development

   Team members can work on different layers of the stack simultaneously, as long as the underlying base is stable.

How Do Stacked Diffs Work?

The process of creating and managing stacked diffs typically involves the following steps:

1. Creating a Base Diff

The base diff contains the foundational changes. For instance, you might begin by refactoring existing code or laying the groundwork for a new feature.

git checkout -b feature/base-change
git commit -m "Base change for feature"

2. Building on the Base

Subsequent diffs are built as branches that depend on the base.

git checkout -b feature/logic-layer feature/base-change
git commit -m "Add business logic layer"

3. Submitting Stacked Changes

Each diff is submitted for review in order. Reviewers evaluate changes layer by layer, ensuring quality at every step.

4. Rebasing Stacks

If changes in a lower layer are updated, higher layers may need to be rebased. Tools like git rebase or platform-specific features help manage this efficiently.

git rebase feature/base-change

Tools Supporting Stacked Diffs

Several tools and workflows facilitate the creation and management of stacked diffs:

1. Git

   Native Git commands like rebase, cherry-pick, and format-patch can be used to emulate stacked diffs manually.

   
   

2. Phabricator

   Popularized stacked diffs as a core feature. It provides an interface for managing dependencies between changes seamlessly.

   
   

3. GitHub & GitLab

   Both platforms now offer ways to link pull requests or merge requests to represent dependencies.

   
   

4. Graphite

   A modern tool specifically designed for managing stacked diffs, focusing on Git workflows.

   
   
   
   

Challenges with Stacked Diffs

While stacked diffs offer significant benefits, they come with some challenges:

1. Developers new to stacked workflows may find it confusing to manage dependencies and rebases.

2. Not all tools and platforms support stacked diffs natively, requiring workarounds or additional software.

3. Large stacks can become difficult to manage, especially if multiple layers require changes simultaneously.

   
   
   
   

Conclusion

Stacked diffs have revolutionized how developers handle complex, interdependent changes. By breaking changes into manageable, sequential units, they improve clarity, facilitate better collaboration, and enhance code quality. While there may be a learning curve, the benefits far outweigh the challenges, making stacked diffs an essential tool for modern development workflows.

As teams continue to embrace stacked workflows, development becomes more efficient and collaborative—setting a new standard for how we build and deliver software.