Document integration of the workflow with pull requests

[IvanVas]

I don't think it's clear would the team get through the PRs process using the branchless workflow.

[arxanas]

Hi Ivan, I didn't understand the what you meant by "would the team get through". Can you explain more about what you would like to know?

[IvanVas]

It's not clear how the branchless workflow is integrating with process of PR creation.
E.g., you're working on several features locally using branchless. At some point you'd like to separate them into branches (grouped by features or other logic) in order to create several PRs. How would you do this?

[jacobsimpson-addepar]

Some notes about what I've been doing so far. There may be other approaches. Also note, I'm pushing the branches and PRs directly to the main repo, not a fork. I'm using Github in the context of my company and we don't fork our repos for development purposes.

As far as I can tell, Github pull requests require branches, so I start by making branches and pushing them:

$ git sl
◇ ed760a5d 12m (master) Initial commit.
┃
◯ 69feacd3 12m Update line 2.
┃
● f32444c3 2m Make line 2 extra verbose
$ git prev
branchless: git checkout HEAD^
Previous HEAD position was f32444c Make line 2 extra verbose
branchless: processing 1 update to a branch/ref
HEAD is now at 69feacd Update line 2.
branchless: processing checkout
◇ ed760a5d 12m (master) Initial commit.
┃
● 69feacd3 12m Update line 2.
┃
◯ f32444c3 3m Make line 2 extra verbose
$ git checkout -b feature-1
branchless: processing 1 update to a branch/ref
Switched to a new branch 'feature-1'
branchless: processing checkout
$ git sl
◇ ed760a5d 12m (master) Initial commit.
┃
● 69feacd3 12m (feature-1) Update line 2.
┃
◯ f32444c3 3m Make line 2 extra verbose
$ git push origin

Then make a PR for it:

$ gh pr create --base main --head feature-1 --fill

It gets a little trickier if you want to stack PRs:

$  git next
branchless: git checkout f32444c38c146749ce04328bbe27aa85cef3d6e0
branchless: processing 1 update to a branch/ref
Note: switching to 'f32444c38c146749ce04328bbe27aa85cef3d6e0'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at f32444c Make line 2 extra verbose
branchless: processing checkout
◇ ed760a5d 19m (master) Initial commit.
┃
◯ 69feacd3 19m (feature-1) Update line 2.
┃
● f32444c3 9m Make line 2 extra verbose
$ git checkout -b feature-2
branchless: processing 1 update to a branch/ref
Switched to a new branch 'feature-2'
branchless: processing checkout
:➜ ) cloned-repo git:(feature-2)
 git sl
◇ ed760a5d 21m (master) Initial commit.
┃
◯ 69feacd3 20m (feature-1) Update line 2.
┃
● f32444c3 11m (feature-2) Make line 2 extra verbose

Then open a new PR. Notice that the base branch of the new PR is the head branch of the previous PR:

$ gh pr create --base feature-1 --head feature-2 --fill

Current problems I'm encountering:

1. I don't have a great process for updating the feature-2 branch after feature-1 branch is squash merged into main. git restack doesn't notice that feature-1 is now part of main, so restack has no effect. It works to rebase the feature-1 branch onto main (which results in the feature-1 branch commits getting dropped because the rebase deduplication algorithm notices the changes are already in main), and then running git restack to get the feature-2 branch stacked up on main. I don't use git rebase to rebase a sequence of branches because it will leave behind all the branch names, except the name of the branch used to identify the rebase. Edit: Looks like git rebase --onto master $(git merge-base master feature-2) feature-2 && git restack does the trick, even when there are several stacked branches.
2. If I do a rebase and reorder the branches (feature-1 -> feature-2 -> main), the PR for feature-2 will get auto closed. When I push feature-2 branch to Github, it notices that feature-1 branch is no longer an ancestor and closes the PR as merged.

[arxanas]

@jacobsimpson-addepar Check out the latest release at #73. git move should now help with cleaning up stale branches.

[jacobsimpson-addepar]

I'll update and have a go. Thanks.

[arxanas]

Actually, try installing from the latest source (with cargo install --git https://github.com/arxanas/git-branchless). It includes deduplication by patch ID, which matches what git rebase does. It didn't make it into the latest release because I was still resolving performance issues on large repositories.

[jacobsimpson-addepar]

Done. I didn't actually realize there were releases. I've been following the README installation instructions: https://github.com/arxanas/git-branchless#installation

[IvanVas]

Thanks, great answers! I think it merits a place in the readme.

[arxanas]

@jacobsimpson-addepar thanks for detailing your workflow. I'll need to synthesize a "blessed" Github workflow into a` guide in the wiki at some point.

Have you tried either of https://github.com/ezyang/ghstack or https://github.com/timothyandrew/gh-stack to help with your workflow? I'm curious to know if they help, or if they still have shortcomings.

It works to rebase the feature-1 branch onto main (which results in the feature-1 branch commits getting dropped because the rebase deduplication algorithm notices the changes are already in main

I've added this as one of the work items in #34, as we should be able to detect duplicated commits. The implementation is a bit tricky to integrate with git rebase. Apparently, I also don't understand the rebase deduplication algorithm, because I thought it operated only on the level of commits, so it won't be able to detect a squash-merge. I'll have to research it more.

It should also be possible to delete branches which have been merged upstream in the same way.

Edit: Looks like git rebase --onto master $(git merge-base master feature-2) feature-2 && git restack does the trick, even when there are several stacked branches.

Hopefully we can simplify this into a single git move -b feature-2 -d master or something like that, or make a git sync command which does it automatically.

[terinjokes]

I've been using Stacked Git for several years now in a branch-less workflow, primarily one commit per review. To manage pull requests in our internal (non-GitHub) review tool has been to shuffle the stack around until only the commit I want is on the stack, then push to a remote branch named after the patch name.

git push -f origin $(stg id):refs/heads/patches/$(stg top)

I'm unsure what I should do with git-branchless. Neither of the tools recommended previously (ghstack and gh-stack) work well here, since they rely on the GitHub API.

[arxanas]

When you say "shuffle" until only the commit you want is in the stack, you mean essentially to excise one particular commit and place it on the main branch, then it would probably require #176, and then you could write git move -x <commit> main.

I don't have a way in mind to get the hash of the commits moved by git move. I suppose you could attach a branch to it, which would then be moved along with it. Is that an indispensable part of your workflow?

[terinjokes]

Shuffle meaning some combination of stg pop and stg push. I don't think this is an indispensable part of my workflow, if there's a better way to create remote branches of just a specific series of commits. I was just concerned by these two discussions seemingly focused on only the GitHub workflow.

[arxanas]

Well, it is a discussion around "pull requests", which I assumed was a Github-specific thing :). I appreciate your feedback as a Stacked Git user, as I haven't used it myself, but git-branchless is supposed to power the same kinds of workflows. Feel free to open more discussions on deficiencies in relation to Stacked Git.

I think the way I currently handle this is to use git rebase -i to commute any commits I want to get reviewed to the top of the stack, then run git move -s HEAD -d main (or HEAD~3 or whatever commit for -s) to separate them from the rest of the commits. Have you tried using git rebase -i for that kind of workflow?

[terinjokes]

Well, it is a discussion around "pull requests", which I assumed was a Github-specific thing :

Ah. I read "pull requests" and assumed the discussion extended to other ways of getting code to reviewers, such as GitLab's Merge Requests, Gerrit's changesets, Linus's Alpine, or BitBucket's Pull Requests. Especially with one of these discussions including Phabricator. :)

Feel free to open more discussions on deficiencies in relation to Stacked Git.

Will do, though I'm still catching up on the existing issues and discussions. I'm able happy to jump on a chat to discuss workflows.

Have you tried using git rebase -i for that kind of workflow?

I've switched one repository of mine to using git-branchless today, so I haven't yet. I can give this a shot.