How do stacked diffs work

Greg Foster
Greg Foster
Graphite software engineer

In the realm of software development, the methodology employed for version control and code review can dramatically impact the productivity and collaboration of a development team. Stacked diffs represent a pivotal innovation in this space, promising to streamline the code review process with their unique approach to managing code changes. This guide delves into the inner workings of stacked diffs, revealing their integration with existing development tools and illuminating their importance in modern development workflows.

Stacked diffs refer to a sequence of code changes where each change is based on the last, forming a hierarchical stack. Unlike traditional pull requests that bundle changes, stacked diffs segregate updates into digestible, reviewable pieces.

  • Directed Acyclic Graph (DAG) of Branches:

    • Each branch in the stack represents a coherent idea or change.

    • The DAG structure allows for a clear hierarchy and dependencies between changes.

  • Difference from Other VCS Constructs:

    • Commit: A single snapshot of changes.

    • Pull Request (PR): A merge request for a series of commits.

    • Branch: An independent line of development.

    • Stacked Diff: A stack of branches where each branch is an idea that builds on the previous branch in the stack.

  • Review and CI Compatibility:

    • Each branch in the stack is independently reviewable and can pass CI checks before being merged.
# Start with the base branch
git checkout main
# Create a new branch for the first diff
git checkout -b feature/base-diff
# Commit changes for the first diff
git add .
git commit -m "Implement base feature"
# Create a second diff based on the first
git checkout -b feature/second-diff
# ... make changes and commit them ...
  • Branch as a Storage Unit:

    • Each diff is stored as a branch, with the possibility of containing one or more commits.
  • Flexibility:

    • A branch in the stack can contain multiple commits if they belong to the same logical change.
  • Integration:

    • Stacked diffs are integrated by merging or rebasing branches in sequential order, from the bottom of the stack upwards.

Note: While stacked diffs offer a structured approach to managing changes, the concept may require a shift in workflow for teams accustomed to more traditional methods. It's essential to ensure all team members are familiar with the concept to utilize stacked diffs effectively.

To create a stacked diff, developers start with a base branch and make a series of changes, each dependent on the last. Tools like Graphite facilitate this process with commands like gt stack create and gt diff stack.

# Starting a new stack
gt stack create "refactor-authentication"
# Adding a diff to the stack
gt diff add "implement-two-factor-auth"

Stacked diffs create an environment where code reviews are both efficient and thorough. Smaller diffs mean that reviewers can focus on each change in isolation, leading to faster and more focused reviews. This process not only makes the review quicker but also increases the likelihood of catching errors, as the cognitive load is significantly reduced.

Testing each diff individually ensures that any issues are caught and addressed early, without the interference of other changes. This isolation is a perfect fit for continuous integration workflows, as each change triggers its own build and test process, offering:

  1. Immediate feedback on the latest changes.

  2. Early detection and resolution of bugs.

  3. Consistent quality assurance throughout the development lifecycle.

  • Non-blocking workflow: Developers can move on to the next task without waiting for previous changes to be merged.

  • Focused communication: Discussions are more productive when they revolve around smaller, isolated changes.

  • Stable main branch: By merging changes incrementally, the stability of the main branch is preserved.

  • Reduced merge conflicts: Smaller, focused changes lead to fewer conflicts, simplifying code integration.

Note: Incremental integration facilitates a smoother development process, as developers can address potential issues in smaller, more manageable increments.

Stacked diffs effectively minimize delays in the development process by allowing parts of a feature to move forward independently. This aspect of stacked diffs is critical in maintaining a continuous delivery pipeline, ensuring that dependencies or lengthy review processes do not stall development.

In conclusion, the implementation of stacked diffs within a development team's workflow brings forth a multitude of benefits, from improved code quality to enhanced collaboration. It is an approach that aligns with the agile methodology and responds well to the dynamic demands of modern software development.

Stacked diffs are compatible with popular version control systems like Git, integrating seamlessly into existing workflows.

Graphite provides a suite of commands designed to manage stacked diffs efficiently, aligning with the developer's existing toolkit and streamlining the diff management process.

# Checking out a diff from the stack
gt diff checkout "implement-logging"
# Reviewing the stack
gt stack review

Stacked diffs are revolutionizing the code review process, offering a structured and incremental approach to managing code changes. By embracing this methodology, development teams can enhance efficiency, improve code quality, and foster a more collaborative environment. As the software development industry continues to evolve, the adoption of stacked diffs is becoming a hallmark of progressive, agile teams poised for success.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2