github-desktop/docs/technical/rebase-flow.md

# Rebase Flow

This document outlines the technical details about the rebase flow as
implemented in GitHub Desktop. It is intended to be a simple subset of what is
technically possible to do with the `git rebase` command line interface, and
various decisions have been made along the way to support this flow.

## Testing the rebase

When the user is choosing which branch to rebase the current branch on, the
application is expected to test and identify whether there will be problems with
the rebase:

 - In the "happy path" case, there will be no conflicts when rebasing this
 branch on top of the chosen branch, and the number of commits that will be
 rebased is shown

 - If conflicts are expected that the user is required to resolve to rebase the
 current branch on top of the chosen branch, the application should provide a
 warning. Ideally the application would be able to identify the absolute number
 of conflicts, but because of the cascading nature of rebases (after the user
 resolves conflicts in one commit, the following commits may introduce conflicts
 that were not previously known) this is not able to be quantified definitively.

To work out this information, we need to _emulate_ a Git rebase and test out the
changes without making changes to the working directory or the Git index. To do
this, we need to:

 1. identify the commits that Git would apply from the target branch
 2. generate a patch that represents the changes the rebase would apply to the
   base branch
 3. test this patch and see if it applies cleanly to the base branch

Steps 2 and 3 are not currently implemented, but are being tracked in
[#6960](https://github.com/desktop/desktop/issues/6960).

The next section walks through these steps in more detail, referencing the
underlying Git implementation.

### Identifying the commits to rebase

The rebase flow that Desktop currently uses is the simple
`git rebase <upstream> <branch>`. In the rest of this document I will refer to
`<upstream>` as the **base branch** and `<branch>` as the **target branch**, to
differentiate from the upstream remote.

When `git` invokes `git rebase <upstream> <branch>` it performs these steps as
setup:

 1. confirm `<upstream>` and `<branch>` are valid references in the repository,
    and resolve the `oid` of each ref
 2. find the range of commits from `<upstream_oid>..<branch_oid>`
 3. generate a patch series of the contents, ready to rebase

### Detecting Conflicts

**TODO:** As part of detecting conflicts in [#6960](https://github.com/desktop/desktop/issues/6960)
there will be some words here eventually to help explain how the solution works.

## Warning about remote commits

If the target branch is tracking a remote branch and the user has enabled the
_Show confirmation dialog before force pushing_ setting, Desktop
will check if any commits exist in the range
`<upstream_oid>..<remote_branch_oid>` before starting the rebase, where `<remote_branch_oid>` is the tip of
the tracking branch.

This check is important to identify any remote commits that will be caught in
this rebase, because their existence would require rewriting the history on the remote,
which the user may not have permission to do based on branch protections or may not want to do because of the impact it can have on other collaborators.

If commits are found, a dialog is shown to ask the user to confirm they wish
to proceed with the rebase.

## Reporting Progress

When the user launches the rebase, the application will run
`git rebase <upstream> <branch>` behind the scenes, which progress information
to `stdout` as it works through the process of applying commits to the base
branch to create the new history.

Desktop is able to parse this output and use in the application, but because
this is all working locally it is typically very fast on machines with good I/O,
the application will make the rebase appear slower than it actually is so that
it can transition smoothly between "progress" and the end states of the rebase
without confusing the user.

## Encountering conflicts

Once the `git rebase <upstream> <branch>` has completed Desktop inspects the
output returned by `git`. The rebase will end up in one of two states:

 - the commits from the target branch were applied cleanly, and the reference
   associated with the target branch now points  to the rewritten history on top
   of the base branch.
 - the rebase could not complete because one of the commits had conflicts when
   it was applied to the base branch, and the user needs to resolve these
   conflicts if the user wishes to resolve them

This section will focus on the second scenario, and what Desktop does to surface
this context to the user to help them figure out how to resolve conflicts.

When a rebase is in a conflicted state, the `.git` directory has
a bunch of helpful context to help the user orient themselves and to figure out
what is next.

#### Is a rebase in progress?

The `.git/REBASE_HEAD` file exists when the rebase is stopped because of
conflicts, and contains the commit ID of the current patch that cannot be
applied cleanly to the working directory

#### Details about the rebase

The information about what changes are being rebased can be identified found
from a few files:

 - `.git/rebase-merge/head-name` - the name of the target branch associated with
    the current rebase - may be prefixed with `refs/heads/`

**TODO**: can we confirm when this happens or doesn't happen?

 - `.git/rebase-merge/onto` - the commit ID of the base branch, which is used as
    a starting point to apply the commits from the target branch

 - `.git/rebase-merge/orig-head` - the original commit ID of the target branch

This information is especially helpful if Desktop encounters a repository which
had the rebase started outside Desktop but encountered conflicts - with this
information the application can identify the current situation and continue
with resolving conflicts without needing to restart the operation.

#### Details about the rebase progress

If a rebase was not started outside Desktop, or the rebase flow is paused, the
details about the progress state can be built up from these fields.

When a rebase encounters conflicts, the patches themselves are stored in files
in `.git/rebase-merge/` in numeric order of which they will be applied, e.g.
`0001`, `0002`, `0003` and so on.

**TODO**: can we confirm whether `9999` is the upper limit here for the rebase?

 - `.git/rebase-merge/msgnum` - this contains a number representing the current
   patch being applied as part of the rebase.
 - `.git/rebase-merge/end` - this number contains the total number of patches
   that will be applied as part of this rebase
 - `.git/rebase-merge/orig-head` - the original commit ID of the target branch
 - `.git/rebase-merge/onto` - the commit ID of the base branch, which is used as
    a starting point to apply the commits from the target branch

The last two files, `orig-head` and `onto` can be used to generate a range of
commits which are part of the rebase, without needing to read all the patch
files in the directory.

## Completing the rebase

After detecting that the user has resolved all conflicts in the working
directory - both in files with conflict markers and files requiring a manual
resolution ("ours" or "theirs") - the rebase flow will determine what the next
rebase action should be.

After staging all the tracked files, if there are no changes in the index this
means the current commit is a no-op and the changes it contains are already
available in the base branch. This means the commit can be omitted by the
rebase by running `git rebase --skip`.

If there are changes in the index after staging all the changes, the rebase flow
will run `git rebase --continue` to indicate the current commit should be
updated and used in the rebased branch.

And like before, the rebase flow will monitor the output from this new rebase
command and report progress, until it either completes or encounters conflicts
again.

## Aborting the rebase

If the rebase encounters conflicts, the user has the opportunity to abort the
rebase if they feel uncomfortable with proceeding.

If the user has resolved conflicts before trying to abort, the rebase flow will
ask the user to confirm they wish to abort the rebase, as those changes will not
be available if they proceed.

## Force Push

When the rebase is completed, the application will update its list of rebased
branches to indicate that the current branch was updated by the user and is
eligible to be "force pushed" to the remote repository.

This has potential downsides, so there are additional checks as part of this
work:

 - only a branch that completed the rebase flow in Desktop will be eligible for
 a "force push" operation - branches rebased outside Desktop will be ignored
 - other branches which are ahead and behind will need to have these commits
 resolved before any commits can be pushed. Depending on your Git configuration,
 this could be a `pull with rebase` or a `pull with merge` commit
 - if the user has enabled "Show Confirmation Dialog before Force Pushing"
 (enabled by default), the user will see a prompt that explains the downstream
 impact of rewriting the branch for other contributors
 - when Desktop invokes `git push` it will also pass the `--force-with-lease`
 flag that guards against the tracking branch being updated without the user
 knowing, to avoid overwriting newer commits since the rebase was completed