Design: git sync

[arxanas]

The git sync command would rebase all current draft commits onto the main branch.

Suggested interface:

• -u/--update-refs option would be optional, to run git fetch first, not provided by default. Some people complain that git pull is a bad default abstraction. There are reasons to avoid fetching refs by default, such as to improve determinism for intelligibility reasons and to avoid unnecessarily spoiling build artifacts on disk.
• -m/--merge (and related options) would be optional, to attempt to resolve merge conflicts. By default, it's probably best to sync only stacks which cleanly apply. (Personally, it was a big problem for me when I wanted to update work but not immediately resolve conflicts.)

Currently, rebases are calculated in two steps. First, we plan the rebase, which involves deduplicating commits and creating the rebase steps, which might be executed either in-memory or on-disk. Then we execute the rebase, which involves applying the patches, either in-memory or on-disk.

What should we do in parallel? We can execute multiple in-memory rebases at the same time, but what if one of them has conflicts? Presumably we should serialize the order in which conflicts are resolved? See also the next point.

Should git sync be one logical transaction or many? For example, if one stack applies cleanly and another one has conflicts, and then you abort the rebase, surely it shouldn't undo the sync that applied cleanly.

What order should stacks be rebased in logically, if any? For determinism, it probably makes sense to carry out the rebasing of multiple stacks in the same order each time. That way, if you abort merge conflict resolution and run git sync again later, it restarts the same merge conflict resolution, instead of potentially throwing you into an unrelated one from a different stack.

What should we do about stacks with multiple roots? This is possible if one of the stacks has a merge commit at the bottom. If you rebase such a stack on top of the main branch, then would the merge commit become a single-parent commit?

Can we cache commit deduplication? It can take a few seconds to examine the upstream patches when you run git sync. If you first do an in-memory git sync and then follow up with a git sync --merge to get the rest of the stacks, then you have to incur the overhead twice. In my opinion, it's not worth solving this problem for now.

[epage]

-u/--update-refs option would be optional, to run git fetch first, not provided by default. Some people complain that git pull is a bad default abstraction. There are reasons to avoid fetching refs by default, such as to improve determinism for intelligibility reasons and to avoid unnecessarily spoiling build artifacts on disk.

git-stack calls this --pull. I could also see calling it --fetch in this context. I think these names make sense for people coming over from git pull --rebase. Otherwise, I'd see --update-refs and be unsure what it does and my understanding would be dependent on the quality of the documentation.

[arxanas]

I didn't use --fetch since the short flag would be -f, which looks like --force, and it might be misleading or we might want to use that flag in the future. I think ideally, if I were making a new SCM, I would call the flag just --update, but since we're targeting Git users, --pull would probably be the best option overall.