{"article":{"slug":"stacked-diffs-with-maiao","title":"Stacked diffs with Maiao","subtitle":null,"summary":"kqr of Entropic Thoughts describes using the community fork of Maiao to work with stacked diffs in git, how the workflow compares with keeping a branch per atomic change, and the pitfalls of dependent and independent changes.","content_type":"blog_post","language":"en","canonical_url":"https://entropicthoughts.com/stacked-diffs-with-maiao","author":{"name":"kqr","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Entropic Thoughts","url":null,"listing_slug":null,"listing":null},"topics":[{"name":"programming","slug":"programming","url":"https://listedarticles.com/topics/programming"},{"name":"git","slug":"git","url":"https://listedarticles.com/topics/git"},{"name":"developer-tools","slug":"developer-tools","url":"https://listedarticles.com/topics/developer-tools"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":2532,"reading_minutes":11,"published_at":"2026-11-16T23:00:00.000Z","added_at":"2026-11-18T07:48:45.075Z","updated_at":"2026-11-18T07:48:45.075Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/stacked-diffs-with-maiao","markdown_url":"https://listedarticles.com/articles/stacked-diffs-with-maiao.md","example":false,"citation":"kqr, Entropic Thoughts. \"Stacked diffs with Maiao.\" 16 Nov 2026. https://entropicthoughts.com/stacked-diffs-with-maiao (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://entropicthoughts.com/stacked-diffs-with-maiao"},"body_markdown":"# Stacked diffs with Maiao\n\nby kqr,\npublished 2026-11-17\n\nTags:\n\n- [programming](https://entropicthoughts.com/tags.html#programming)\n\n![stacked-diffs-with-maiao.jpg](https://entropicthoughts.com/image/banner/stacked-diffs-with-maiao.jpg)\n\nOn the go? [Listen to an ai-narrated version of this article](https://entropicthoughts.com/audio/stacked-diffs-with-maiao.opus).\n\nConfused? [More about ai narration](https://entropicthoughts.com/ai-narration).\n\nI have been using [the community fork of Maiao](https://github.com/runetes/maiao) for a little while now, and it is\nexcellent. For anyone who prefers working with stacked diffs, but needs to\ninteract with a more traditional forge such as GitHub, try using Maiao for a\nbit. *It just does the right thing in almost every situation*. It’s cut my\nfrustration with GitHub at least in half, if not more.\n\nFor the small group of readers who are stoked about stacked diffs, that’s\nprobably enough of a pitch. For the rest of the world, let’s back up a little.\n\n# [The pull request as the unit of change](#the-pull-request-as-the-unit-of-change)\n\nOn traditional forge platforms11 Like GitHub, Codeberg, GitLab, BitBucket,\netc., pre-commit22 Pre-commit because it’s the review that happens before the\ncode is merged (“committed”) to the upstream branch, in contrast to e.g. audits\nwhich are a kind of post-commit review. code review happens on *pull requests*\n(sometimes called *merge requests*), where each pull request is created from a\ngit branch.\n\nUsers that are new to git can then think of a branch as one development effort\ntoward a small goal. They keep adding commits to that branch as long as its tip\ndoes not represent the goal state. At the end, when everything looks right and\nthe change is approved, they perform an explicit merge. This means they create a\nmerge commit on the upstream branch that references both the old upstream and\nthe branch they worked on.\n\nThis lets beginners work in smaller increments while not dealing with the\nintricacies of rewriting git history33 Sometimes the beginner is instructed to\nperform a squash merge instead, which typically means the forge platform creates\na single, regular commit on the upstream branch, referencing only the old\nupstream, and containing all the changes implied by the tip of the development\nbranch. Although it sounds like this rewrites history, it doesn’t really – the\nold development branch is still exactly the same as it was before. The\ndifference is that the changes implied by it were copied over to the upstream\nbranch without reference to the development branch.; the workflow lowers the\nbarrier to collaborating with others using git, which is nice.\n\nIt also means *the reviewing interface* in a traditional forge doesn’t have to\ndeal with the intricacies of rewriting git history. This means the reviewing\nui typically only shows the differences between commits still on the\ndevelopment branch, and not what changed between two versions of “the same”\ncommit, when one of them is no longer on the branch.\n\nTo be more concrete, here’s an example of a part of the history graph of a\nproject that uses this workflow.44 The commits are not shown in chronological\norder. I reordered them (where it was possible to do so without changing the\nstructure of the graph) to make the graph read more clearly.\n\n```\n▲ (upstream)\n│\n│   ▲ (input-validation)\n│   │\n│   │   ▲ (priv-cache)\n│   │   │\n│   ●   │       Tighten input validation\n│   │   │\n│   │   ●       Rename cache variables\n│   │   │\n│   │   ●       Cache user permissions\n├───╯   │\n●◀──╮   │   Merge flaky-test-fix (PR #835)\n│   ├───╯\n│   ●           Fix timezone offset instead\n│   │\n│   ●           Disable login test\n│   │\n●◀──┼───╮   Merge log-migration (PR #834)\n├───╯   │\n●◀──╮   │   Merge avatar-upload (PR #833)\n│   │   │\n│   ●   │       Fix typo in readme\n│   │   │\n│   ●   │       Clean up unused imports\n│   │   │\n│   ●   │       Add avatar upload\n├───╯   │\n●◀──╮   │   Merge parser-null-check (PR #832)\n│   │   │\n```\n\nWe can see a total of 12 commits. Four of them are merge commits on the\nupstream branch, and two of those merge commits correspond to branches we can\nsee the work on (`avatar-upload` and `flaky-test-fix`). We can see each of those\ntwo branches had three and two commits of actual work on them, respectively.\n\nThen there are two more branches (`input-validation` and `priv-cache`) which are\nstill open (not merged with upstream). One of them (`priv-cache`) has two\ncommits of work, and it’s not based on the upstream branch, but on the final\nresult of one of the earlier branches (`flaky-test-fix`), before it got merged.\n\n# [The commit as the unit of change](#the-commit-as-the-unit-of-change)\n\nWe don’t have to use git that way. We can instead choose to have only *one*\ndevelopment branch. I call it something generic like `dev`. On that branch, each\ngoal state is represented by one commit. So instead of multiple branches (one\nfor each goal) with multiple commits on them (steps toward the implementation),\nthere is just one branch (a generic development branch) with multiple commits on\nit (one for each goal).\n\n## [Fixing up existing commits](#fixing-up-existing-commits)\n\nWith that workflow, if we discover one of the commits don’t represent the goal\nstate of that change, *we edit that commit*55 Technically speaking, git\ndoesn’t let users edit commits. What happens under the hood is the commit is\nreplaced with a new one. But with a change id in the commit message, we can\nstill tell that they represent the same atomic change. instead of adding more\ncommits.66 What if we need to revert to an old commit? Fortunately, git\nmaintains a reflog with old commits. Those stick around until git decides to\ngarbage collect dangling refs. Then each atomic change in progress is\nimplemented in exactly one commit, all on one development branch. The `dev`\nbranch may have many commits, but they represent different atomic changes, not\nprogress toward one goal state.\n\nThis way of working is also known as making *stacked diffs*, and I find it\neasier and faster than having a separate branch for each atomic change. [Many](https://newsletter.pragmaticengineer.com/p/stacked-diffs)\nexperienced [software](https://gregoryszorc.com/blog/2020/01/07/problems-with-pull-requests-and-how-to-fix-them/) engineers [agree](https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/).77 I should say I disagree with Gergely\nOrosz when he says it’s impossible to make a pull request that depends on\nchanges in an earlier, unmerged pull request. It’s possible (and even easy in\nmost forges) but it’s a lot of extra work to juggle the branches and merge\ntargets. Fundamentally, there’s no deep incompatibility between pull requests\nand stacked diffs. The reason people prefer tooling made for stacked diffs is\nthat there’s less paperwork needed to satisfy git when working with those\ntools.\n\n## [Merging stacked diffs](#merging-stacked-diffs)\n\nThe way stacked diffs are merged is ideally by copying them over to the upstream\nbranch, either through cherry-picking, or by choosing the *rebase and\nfast-forward* merge type in the forge ui. This produces a history of the\nupstream branch that very clearly lists each atomic change in the order it\noccurred, without the false steps and mistakes along the way.\n\nBeginners may think this is dishonest. The the point is not to hide one’s\nmistakes, but to present a history that another developer can read and follow\nalong with three years into the future, when they want to understand how the\nproject ended up in the state it is in. For that purpose, only what eventually\nwent into the upstream branch matters.\n\n## [Revisiting the history graph](#revisiting-the-history-graph)\n\nThe example history graph from above would, under a stacked diffs-type\nworkflow, look more like this:\n\n```\n▲ (upstream)\n│\n│    ▲ (dev)\n│    │\n│    ●       Tighten input validation\n│    │\n│    ●       Cache user permissions\n│    │\n●◁┄┄┄◌   Fix timezone offset in login test (PR #835)\n├───▶┤\n●    │   Migrate to structured logging (PR #834)\n│    │\n●◁┄┄┄◌   Allow users to upload avatars (PR #833)\n├───▶┤\n●    │   Check for null in order parser (PR #832)\n│    │\n```\n\nTwo commits on the upstream branch (null check and timezone offset) came from\nother people. In between them, we updated our long-lived `dev` branch to reflect\nthe latest upstream, and then copied the finished avatar commit over to the\nupstream. The same process happened for the flaky test fix a little later. We\nworked on both user permission caching and input validation in the same `dev`\nbranch instead of making two separate, new branches. Once those commits are\napproved and have passed through ci, they will get copied to the upstream\nbranch, like the ones before them.\n\nAll of these commits needed amendment just as many times as in the previous\ngraph, only we do it by replacing the commits instead of adding more commits.\n\nThis is what people mean when they talk about how “one atomic change is one\ncommit, and one commit is one atomic change”.\n\n## [The drawback of stacked diffs](#the-drawback-of-stacked-diffs)\n\nThere is one unfortunate consequence of the stacked diffs workflow: when all\ncommits are in one branch, they look like they depend on each other in the order\nthey exist on the branch, even if they actually contain independent changes.\nWhen all commits are on one branch, there’s no way to see which commits are\nindependent without (a) reading the code, and (b) trying to cherry-pick one of\nthe changes.88 Both are needed, because cherry-picking or rebasing can\nconflict in git even though changes are independent (when they happen to appear\nclose to each other in the source code), and dependent changes can generate a\nclean cherry-pick as far as git is concerned, even if it breaks the code (when\nthe changes happen in different locations in the code, but one of them assumes\nthe other has happened already).\n\nIf it’s important to document to ourselves that we have two parallel workstreams\nthat are indepedent, we can use two local generic development branches (I call\nmine `dev` and, imaginatively, `dev2`). Each branch is still treated as a stack\nof diffs, i.e. each commit represents one atomic change, but now it’s abundantly\nclear that commits cannot depend on each other across the two branches.\n\n# [Stacked diffs are annoying with pull requests](#stacked-diffs-are-annoying-with-pull-requests)\n\nAt this point, you can probably guess why the pull request workflow of\ntraditional forges is annoying. The pull request assumes we have one branch for\neach atomic change, but with stacked diffs, we only have the one branch, where\nwe want each *commit* to become a separate pull request, building on the one\nbefore it.\n\nThe way I used to handle it was exactly through the tedium you wouldn’t expect:\n\n1. I manually created one branch for each commit.\n2. I pushed all those branches.\n3. I went to the GitHub web ui and made a pull request for each branch, taking\n   care to set the merge target of each to the branch that came before it.\n4. When merging, I again had to be careful to merge in the right order.\n\nThis is a lot of work.99 Still less work in total than having a branch per\natomic change, but just barely! Maiao solves that.\n\n# [Maiao is automation at its finest](#maiao-is-automation-at-its-finest)\n\nThese days, when I feel ready to create pull requests for my commits, I trigger\nthe `git review` command. Maiao then automatically does all of the things I did\nmanually before, better than I could. It fetches the latest upstream, rebases\nthe current branch onto it, creates disposable branches for each commit, pushes\nthem, opens up a pull request with the right merge target for each disposable\nbranch through the GitHub api, and turns them into a native GitHub stack of\npull requests, meaning they get merged in the right order, and can be merged all\nat once when they are ready.\n\nIf code review or the ci build uncovers things I need to change, I do what I\nalways did: I replace the commit that needs changing. Then I run `git review`\nagain, and Maiao *just does the right thing*: it rebases onto the latest\nupstream again, it moves the disposable branches to the new commits,\nforce-pushes them, updates the pull request descriptions with any changes to the\ncommit messages, updates any merge targets that have changed, etc.\n\nMaiao is one command (`git review`). When run, it makes the GitHub pull request\nstack match our local development branch. That’s all it does, and that’s all it\nneeds to do.\n\n## [Dealing with multiple branches and unfinished work](#dealing-with-multiple-branches-and-unfinished-work)\n\nIn cases where we have multiple local development branches (because the work is\nindependent and parallel), `git review` can be run on either or both of them\nindependently of the other, and Maiao will create one stack for each branch, as\none would expect.\n\nNote also that Maiao doesn’t have to create pull requests for the entire\ndevelopment branch. Maybe we’re still working on the top few commits. Then we\ncan create a temporary branch pointing to the topmost of the commits we do want\npull requests for. When we run `git review` with that branch checked out, Maiao\nmakes pull requests only out of the commits included in that branch. Then when\nwe finish those top commits, we can run `git review` on the development branch,\nand Maiao understands that the topmost commits build on the commits that already\nhave pull requests, so it stacks new pull requests for the new commits on top of\nthe pull requests that already existed for the prior commits.\n\nAll of the above to say Maiao doesn’t care about how you branch locally. A\ndecent mental model is that it creates and updates pull requests for each of the\ncommits between `head` and the master branch so the stack on the forge matches\nthe local commits. That’s all.\n\nAnd it’s awesome.\n\n# Sidenotes\n\n[1](#fnr.1)\n\nLike GitHub, Codeberg, GitLab, BitBucket,\netc.\n\n[2](#fnr.2)\n\nPre-commit because it’s the review that happens before the\ncode is merged (“committed”) to the upstream branch, in contrast to e.g. audits\nwhich are a kind of post-commit review.\n\n[3](#fnr.3)\n\nSometimes the beginner is instructed to\nperform a squash merge instead, which typically means the forge platform creates\na single, regular commit on the upstream branch, referencing only the old\nupstream, and containing all the changes implied by the tip of the development\nbranch. Although it sounds like this rewrites history, it doesn’t really – the\nold development branch is still exactly the same as it was before. The\ndifference is that the changes implied by it were copied over to the upstream\nbranch without reference to the development branch.\n\n[4](#fnr.4)\n\nThe commits are not shown in chronological\norder. I reordered them (where it was possible to do so without changing the\nstructure of the graph) to make the graph read more clearly.\n\n[5](#fnr.5)\n\nTechnically speaking, git\ndoesn’t let users edit commits. What happens under the hood is the commit is\nreplaced with a new one. But with a change id in the commit message, we can\nstill tell that they represent the same atomic change.\n\n[6](#fnr.6)\n\nWhat if we need to revert to an old commit? Fortunately, git\nmaintains a reflog with old commits. Those stick around until git decides to\ngarbage collect dangling refs.\n\n[7](#fnr.7)\n\nI should say I disagree with Gergely\nOrosz when he says it’s impossible to make a pull request that depends on\nchanges in an earlier, unmerged pull request. It’s possible (and even easy in\nmost forges) but it’s a lot of extra work to juggle the branches and merge\ntargets. Fundamentally, there’s no deep incompatibility between pull requests\nand stacked diffs. The reason people prefer tooling made for stacked diffs is\nthat there’s less paperwork needed to satisfy git when working with those\ntools.\n\n[8](#fnr.8)\n\nBoth are needed, because cherry-picking or rebasing can\nconflict in git even though changes are independent (when they happen to appear\nclose to each other in the source code), and dependent changes can generate a\nclean cherry-pick as far as git is concerned, even if it breaks the code (when\nthe changes happen in different locations in the code, but one of them assumes\nthe other has happened already).\n\n[9](#fnr.9)\n\nStill less work in total than having a branch per\natomic change, but just barely!\n","body_html":"<h1 id=\"stacked-diffs-with-maiao\">Stacked diffs with Maiao</h1>\n<p>by kqr,\npublished 2026-11-17</p>\n<p>Tags:</p>\n<ul><li><a href=\"https://entropicthoughts.com/tags.html#programming\" rel=\"nofollow ugc noopener\">programming</a></li></ul>\n<figure><img src=\"https://entropicthoughts.com/image/banner/stacked-diffs-with-maiao.jpg\" alt=\"stacked-diffs-with-maiao.jpg\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></figure>\n<p>On the go? <a href=\"https://entropicthoughts.com/audio/stacked-diffs-with-maiao.opus\" rel=\"nofollow ugc noopener\">Listen to an ai-narrated version of this article</a>.</p>\n<p>Confused? <a href=\"https://entropicthoughts.com/ai-narration\" rel=\"nofollow ugc noopener\">More about ai narration</a>.</p>\n<p>I have been using <a href=\"https://github.com/runetes/maiao\" rel=\"nofollow ugc noopener\">the community fork of Maiao</a> for a little while now, and it is\nexcellent. For anyone who prefers working with stacked diffs, but needs to\ninteract with a more traditional forge such as GitHub, try using Maiao for a\nbit. <em>It just does the right thing in almost every situation</em>. It’s cut my\nfrustration with GitHub at least in half, if not more.</p>\n<p>For the small group of readers who are stoked about stacked diffs, that’s\nprobably enough of a pitch. For the rest of the world, let’s back up a little.</p>\n<h1 id=\"the-pull-request-as-the-unit-of-change\"><a href=\"#the-pull-request-as-the-unit-of-change\">The pull request as the unit of change</a></h1>\n<p>On traditional forge platforms11 Like GitHub, Codeberg, GitLab, BitBucket,\netc., pre-commit22 Pre-commit because it’s the review that happens before the\ncode is merged (“committed”) to the upstream branch, in contrast to e.g. audits\nwhich are a kind of post-commit review. code review happens on <em>pull requests</em>\n(sometimes called <em>merge requests</em>), where each pull request is created from a\ngit branch.</p>\n<p>Users that are new to git can then think of a branch as one development effort\ntoward a small goal. They keep adding commits to that branch as long as its tip\ndoes not represent the goal state. At the end, when everything looks right and\nthe change is approved, they perform an explicit merge. This means they create a\nmerge commit on the upstream branch that references both the old upstream and\nthe branch they worked on.</p>\n<p>This lets beginners work in smaller increments while not dealing with the\nintricacies of rewriting git history33 Sometimes the beginner is instructed to\nperform a squash merge instead, which typically means the forge platform creates\na single, regular commit on the upstream branch, referencing only the old\nupstream, and containing all the changes implied by the tip of the development\nbranch. Although it sounds like this rewrites history, it doesn’t really – the\nold development branch is still exactly the same as it was before. The\ndifference is that the changes implied by it were copied over to the upstream\nbranch without reference to the development branch.; the workflow lowers the\nbarrier to collaborating with others using git, which is nice.</p>\n<p>It also means <em>the reviewing interface</em> in a traditional forge doesn’t have to\ndeal with the intricacies of rewriting git history. This means the reviewing\nui typically only shows the differences between commits still on the\ndevelopment branch, and not what changed between two versions of “the same”\ncommit, when one of them is no longer on the branch.</p>\n<p>To be more concrete, here’s an example of a part of the history graph of a\nproject that uses this workflow.44 The commits are not shown in chronological\norder. I reordered them (where it was possible to do so without changing the\nstructure of the graph) to make the graph read more clearly.</p>\n<pre><code>▲ (upstream)\n│\n│   ▲ (input-validation)\n│   │\n│   │   ▲ (priv-cache)\n│   │   │\n│   ●   │       Tighten input validation\n│   │   │\n│   │   ●       Rename cache variables\n│   │   │\n│   │   ●       Cache user permissions\n├───╯   │\n●◀──╮   │   Merge flaky-test-fix (PR #835)\n│   ├───╯\n│   ●           Fix timezone offset instead\n│   │\n│   ●           Disable login test\n│   │\n●◀──┼───╮   Merge log-migration (PR #834)\n├───╯   │\n●◀──╮   │   Merge avatar-upload (PR #833)\n│   │   │\n│   ●   │       Fix typo in readme\n│   │   │\n│   ●   │       Clean up unused imports\n│   │   │\n│   ●   │       Add avatar upload\n├───╯   │\n●◀──╮   │   Merge parser-null-check (PR #832)\n│   │   │</code></pre>\n<p>We can see a total of 12 commits. Four of them are merge commits on the\nupstream branch, and two of those merge commits correspond to branches we can\nsee the work on (<code>avatar-upload</code> and <code>flaky-test-fix</code>). We can see each of those\ntwo branches had three and two commits of actual work on them, respectively.</p>\n<p>Then there are two more branches (<code>input-validation</code> and <code>priv-cache</code>) which are\nstill open (not merged with upstream). One of them (<code>priv-cache</code>) has two\ncommits of work, and it’s not based on the upstream branch, but on the final\nresult of one of the earlier branches (<code>flaky-test-fix</code>), before it got merged.</p>\n<h1 id=\"the-commit-as-the-unit-of-change\"><a href=\"#the-commit-as-the-unit-of-change\">The commit as the unit of change</a></h1>\n<p>We don’t have to use git that way. We can instead choose to have only <em>one</em>\ndevelopment branch. I call it something generic like <code>dev</code>. On that branch, each\ngoal state is represented by one commit. So instead of multiple branches (one\nfor each goal) with multiple commits on them (steps toward the implementation),\nthere is just one branch (a generic development branch) with multiple commits on\nit (one for each goal).</p>\n<h2 id=\"fixing-up-existing-commits\"><a href=\"#fixing-up-existing-commits\">Fixing up existing commits</a></h2>\n<p>With that workflow, if we discover one of the commits don’t represent the goal\nstate of that change, <em>we edit that commit</em>55 Technically speaking, git\ndoesn’t let users edit commits. What happens under the hood is the commit is\nreplaced with a new one. But with a change id in the commit message, we can\nstill tell that they represent the same atomic change. instead of adding more\ncommits.66 What if we need to revert to an old commit? Fortunately, git\nmaintains a reflog with old commits. Those stick around until git decides to\ngarbage collect dangling refs. Then each atomic change in progress is\nimplemented in exactly one commit, all on one development branch. The <code>dev</code>\nbranch may have many commits, but they represent different atomic changes, not\nprogress toward one goal state.</p>\n<p>This way of working is also known as making <em>stacked diffs</em>, and I find it\neasier and faster than having a separate branch for each atomic change. <a href=\"https://newsletter.pragmaticengineer.com/p/stacked-diffs\" rel=\"nofollow ugc noopener\">Many</a>\nexperienced <a href=\"https://gregoryszorc.com/blog/2020/01/07/problems-with-pull-requests-and-how-to-fix-them/\" rel=\"nofollow ugc noopener\">software</a> engineers <a href=\"https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/\" rel=\"nofollow ugc noopener\">agree</a>.77 I should say I disagree with Gergely\nOrosz when he says it’s impossible to make a pull request that depends on\nchanges in an earlier, unmerged pull request. It’s possible (and even easy in\nmost forges) but it’s a lot of extra work to juggle the branches and merge\ntargets. Fundamentally, there’s no deep incompatibility between pull requests\nand stacked diffs. The reason people prefer tooling made for stacked diffs is\nthat there’s less paperwork needed to satisfy git when working with those\ntools.</p>\n<h2 id=\"merging-stacked-diffs\"><a href=\"#merging-stacked-diffs\">Merging stacked diffs</a></h2>\n<p>The way stacked diffs are merged is ideally by copying them over to the upstream\nbranch, either through cherry-picking, or by choosing the *rebase and\nfast-forward* merge type in the forge ui. This produces a history of the\nupstream branch that very clearly lists each atomic change in the order it\noccurred, without the false steps and mistakes along the way.</p>\n<p>Beginners may think this is dishonest. The the point is not to hide one’s\nmistakes, but to present a history that another developer can read and follow\nalong with three years into the future, when they want to understand how the\nproject ended up in the state it is in. For that purpose, only what eventually\nwent into the upstream branch matters.</p>\n<h2 id=\"revisiting-the-history-graph\"><a href=\"#revisiting-the-history-graph\">Revisiting the history graph</a></h2>\n<p>The example history graph from above would, under a stacked diffs-type\nworkflow, look more like this:</p>\n<pre><code>▲ (upstream)\n│\n│    ▲ (dev)\n│    │\n│    ●       Tighten input validation\n│    │\n│    ●       Cache user permissions\n│    │\n●◁┄┄┄◌   Fix timezone offset in login test (PR #835)\n├───▶┤\n●    │   Migrate to structured logging (PR #834)\n│    │\n●◁┄┄┄◌   Allow users to upload avatars (PR #833)\n├───▶┤\n●    │   Check for null in order parser (PR #832)\n│    │</code></pre>\n<p>Two commits on the upstream branch (null check and timezone offset) came from\nother people. In between them, we updated our long-lived <code>dev</code> branch to reflect\nthe latest upstream, and then copied the finished avatar commit over to the\nupstream. The same process happened for the flaky test fix a little later. We\nworked on both user permission caching and input validation in the same <code>dev</code>\nbranch instead of making two separate, new branches. Once those commits are\napproved and have passed through ci, they will get copied to the upstream\nbranch, like the ones before them.</p>\n<p>All of these commits needed amendment just as many times as in the previous\ngraph, only we do it by replacing the commits instead of adding more commits.</p>\n<p>This is what people mean when they talk about how “one atomic change is one\ncommit, and one commit is one atomic change”.</p>\n<h2 id=\"the-drawback-of-stacked-diffs\"><a href=\"#the-drawback-of-stacked-diffs\">The drawback of stacked diffs</a></h2>\n<p>There is one unfortunate consequence of the stacked diffs workflow: when all\ncommits are in one branch, they look like they depend on each other in the order\nthey exist on the branch, even if they actually contain independent changes.\nWhen all commits are on one branch, there’s no way to see which commits are\nindependent without (a) reading the code, and (b) trying to cherry-pick one of\nthe changes.88 Both are needed, because cherry-picking or rebasing can\nconflict in git even though changes are independent (when they happen to appear\nclose to each other in the source code), and dependent changes can generate a\nclean cherry-pick as far as git is concerned, even if it breaks the code (when\nthe changes happen in different locations in the code, but one of them assumes\nthe other has happened already).</p>\n<p>If it’s important to document to ourselves that we have two parallel workstreams\nthat are indepedent, we can use two local generic development branches (I call\nmine <code>dev</code> and, imaginatively, <code>dev2</code>). Each branch is still treated as a stack\nof diffs, i.e. each commit represents one atomic change, but now it’s abundantly\nclear that commits cannot depend on each other across the two branches.</p>\n<h1 id=\"stacked-diffs-are-annoying-with-pull-requests\"><a href=\"#stacked-diffs-are-annoying-with-pull-requests\">Stacked diffs are annoying with pull requests</a></h1>\n<p>At this point, you can probably guess why the pull request workflow of\ntraditional forges is annoying. The pull request assumes we have one branch for\neach atomic change, but with stacked diffs, we only have the one branch, where\nwe want each <em>commit</em> to become a separate pull request, building on the one\nbefore it.</p>\n<p>The way I used to handle it was exactly through the tedium you wouldn’t expect:</p>\n<ol><li>I manually created one branch for each commit.</li><li>I pushed all those branches.</li><li><p>I went to the GitHub web ui and made a pull request for each branch, taking</p><p> care to set the merge target of each to the branch that came before it.</p></li><li>When merging, I again had to be careful to merge in the right order.</li></ol>\n<p>This is a lot of work.99 Still less work in total than having a branch per\natomic change, but just barely! Maiao solves that.</p>\n<h1 id=\"maiao-is-automation-at-its-finest\"><a href=\"#maiao-is-automation-at-its-finest\">Maiao is automation at its finest</a></h1>\n<p>These days, when I feel ready to create pull requests for my commits, I trigger\nthe <code>git review</code> command. Maiao then automatically does all of the things I did\nmanually before, better than I could. It fetches the latest upstream, rebases\nthe current branch onto it, creates disposable branches for each commit, pushes\nthem, opens up a pull request with the right merge target for each disposable\nbranch through the GitHub api, and turns them into a native GitHub stack of\npull requests, meaning they get merged in the right order, and can be merged all\nat once when they are ready.</p>\n<p>If code review or the ci build uncovers things I need to change, I do what I\nalways did: I replace the commit that needs changing. Then I run <code>git review</code>\nagain, and Maiao <em>just does the right thing</em>: it rebases onto the latest\nupstream again, it moves the disposable branches to the new commits,\nforce-pushes them, updates the pull request descriptions with any changes to the\ncommit messages, updates any merge targets that have changed, etc.</p>\n<p>Maiao is one command (<code>git review</code>). When run, it makes the GitHub pull request\nstack match our local development branch. That’s all it does, and that’s all it\nneeds to do.</p>\n<h2 id=\"dealing-with-multiple-branches-and-unfinished-work\"><a href=\"#dealing-with-multiple-branches-and-unfinished-work\">Dealing with multiple branches and unfinished work</a></h2>\n<p>In cases where we have multiple local development branches (because the work is\nindependent and parallel), <code>git review</code> can be run on either or both of them\nindependently of the other, and Maiao will create one stack for each branch, as\none would expect.</p>\n<p>Note also that Maiao doesn’t have to create pull requests for the entire\ndevelopment branch. Maybe we’re still working on the top few commits. Then we\ncan create a temporary branch pointing to the topmost of the commits we do want\npull requests for. When we run <code>git review</code> with that branch checked out, Maiao\nmakes pull requests only out of the commits included in that branch. Then when\nwe finish those top commits, we can run <code>git review</code> on the development branch,\nand Maiao understands that the topmost commits build on the commits that already\nhave pull requests, so it stacks new pull requests for the new commits on top of\nthe pull requests that already existed for the prior commits.</p>\n<p>All of the above to say Maiao doesn’t care about how you branch locally. A\ndecent mental model is that it creates and updates pull requests for each of the\ncommits between <code>head</code> and the master branch so the stack on the forge matches\nthe local commits. That’s all.</p>\n<p>And it’s awesome.</p>\n<h1 id=\"sidenotes\">Sidenotes</h1>\n<p><a href=\"#fnr.1\">1</a></p>\n<p>Like GitHub, Codeberg, GitLab, BitBucket,\netc.</p>\n<p><a href=\"#fnr.2\">2</a></p>\n<p>Pre-commit because it’s the review that happens before the\ncode is merged (“committed”) to the upstream branch, in contrast to e.g. audits\nwhich are a kind of post-commit review.</p>\n<p><a href=\"#fnr.3\">3</a></p>\n<p>Sometimes the beginner is instructed to\nperform a squash merge instead, which typically means the forge platform creates\na single, regular commit on the upstream branch, referencing only the old\nupstream, and containing all the changes implied by the tip of the development\nbranch. Although it sounds like this rewrites history, it doesn’t really – the\nold development branch is still exactly the same as it was before. The\ndifference is that the changes implied by it were copied over to the upstream\nbranch without reference to the development branch.</p>\n<p><a href=\"#fnr.4\">4</a></p>\n<p>The commits are not shown in chronological\norder. I reordered them (where it was possible to do so without changing the\nstructure of the graph) to make the graph read more clearly.</p>\n<p><a href=\"#fnr.5\">5</a></p>\n<p>Technically speaking, git\ndoesn’t let users edit commits. What happens under the hood is the commit is\nreplaced with a new one. But with a change id in the commit message, we can\nstill tell that they represent the same atomic change.</p>\n<p><a href=\"#fnr.6\">6</a></p>\n<p>What if we need to revert to an old commit? Fortunately, git\nmaintains a reflog with old commits. Those stick around until git decides to\ngarbage collect dangling refs.</p>\n<p><a href=\"#fnr.7\">7</a></p>\n<p>I should say I disagree with Gergely\nOrosz when he says it’s impossible to make a pull request that depends on\nchanges in an earlier, unmerged pull request. It’s possible (and even easy in\nmost forges) but it’s a lot of extra work to juggle the branches and merge\ntargets. Fundamentally, there’s no deep incompatibility between pull requests\nand stacked diffs. The reason people prefer tooling made for stacked diffs is\nthat there’s less paperwork needed to satisfy git when working with those\ntools.</p>\n<p><a href=\"#fnr.8\">8</a></p>\n<p>Both are needed, because cherry-picking or rebasing can\nconflict in git even though changes are independent (when they happen to appear\nclose to each other in the source code), and dependent changes can generate a\nclean cherry-pick as far as git is concerned, even if it breaks the code (when\nthe changes happen in different locations in the code, but one of them assumes\nthe other has happened already).</p>\n<p><a href=\"#fnr.9\">9</a></p>\n<p>Still less work in total than having a branch per\natomic change, but just barely!</p>","headings":[{"level":1,"text":"Stacked diffs with Maiao","id":"stacked-diffs-with-maiao"},{"level":1,"text":"The pull request as the unit of change","id":"the-pull-request-as-the-unit-of-change"},{"level":1,"text":"The commit as the unit of change","id":"the-commit-as-the-unit-of-change"},{"level":2,"text":"Fixing up existing commits","id":"fixing-up-existing-commits"},{"level":2,"text":"Merging stacked diffs","id":"merging-stacked-diffs"},{"level":2,"text":"Revisiting the history graph","id":"revisiting-the-history-graph"},{"level":2,"text":"The drawback of stacked diffs","id":"the-drawback-of-stacked-diffs"},{"level":1,"text":"Stacked diffs are annoying with pull requests","id":"stacked-diffs-are-annoying-with-pull-requests"},{"level":1,"text":"Maiao is automation at its finest","id":"maiao-is-automation-at-its-finest"},{"level":2,"text":"Dealing with multiple branches and unfinished work","id":"dealing-with-multiple-branches-and-unfinished-work"},{"level":1,"text":"Sidenotes","id":"sidenotes"}]}}