RFC: git submit interface

[arxanas]

I recently committed a git submit command to master. It just force-pushes a certain set of branches to their respective remotes.

Currently:

• By default, the branches to push are those in stack(). Is that a reasonable default, or is . a better default and the user should have to explicitly write/alias something to push branches in thr current stack?
• Branches which have no upstream are not pushed. You have to pass --create to do so. Is this sensible? I vote yes, since it's a somewhat side-effectful operation. But, then again, so is force-pushing branches at all.
• All branches have to be explicit created by the user.

I'd like to have git submit support both of these workflows:

• Many commits per one code review (primarily for GitHub).
• One commit per one code review (primarily for other code review tools).

The 1:1 approach suggests to me that git submit should be able to synthesize branches to push (jj does this), since there would be a lot of branches to manage. But which of these behaviors should be the default, and how should we opt into the other one?

Since GitHub by default take a n:1 approach, it seems like we should accommodate that by default, and have users opt into a 1:1 workflow with some kind of configuration setting. We could also auto-configure the default behavior of the remote based on whether we think it's GitHub or GitLab, etc.

According to the git-branchless user survey, 8 respondents primarily use GitHub, 3 use GitLab, and 0 use others. (If you haven't already, you can take the user survey here.) You can also see the Stack Overflow developer survey results here: https://survey.stackoverflow.co/2022/#section-version-control-version-control-platforms (top 3 are GitHub, GitLab, BitBucket).

[epage]

Branches which have no upstream are not pushed. You have to pass --create to do so. Is this sensible? I vote yes, since it's a somewhat side-effectful operation. But, then again, so is force-pushing branches at all.

Initially, git would just let you do git push to create a branch upstream. They then switched so you had to pass --set-upstream. As a user, this frustrated me as I never thought "I'm creating a new branch" vs "I'm updating an existing branch'. I just think "I want to push". I ended up creating a git publish alias and have never used git push since despite there being settings that would fix this just because this is ingrained in me.

So I would lean towards creating the branches automatically. To make this safer, it might be interesting to have a "user prefix" so I could configure a epage/ branch prefix and when creating an upstream, the branch name would be epage/<name>. When I've worked at places that encourage that, I've hated dealing with them locally and never set things up to do it for me.

Hmm, started my notes on the idea: gitext-rs/git-stack#241

[claytonrcarter]

At least at this time, my desire is the opposite of @epage ... go figure! I tend to be a cautious user and I dislike the idea that I might inadvertently push branches that aren't ready to be shared. In other commands we have git undo to rollback those whoopsies, but I don't think that could apply here, and suspect that that might be a difficult behavior to sell to new users, or those that are still developing their git mastery. (*cough* like me *cough*)

So I would prefer my default to be "push all of the branches that are tracking a remote, and report which branches were not pushed b/c they're not tracking anything". Then I have the option to retry w/ --create.

Is this something that could be controlled by a config option? As @epage suggested, are there any git config options that could be used to inform what to do here?

[epage]

I dislike the idea that I might inadvertently push branches that aren't ready to be shared

Oh, yeah, forgot to mention another git-stack behavior: it skips branches with WIP / Draft commits. Still need to work more on the WIP story to make it easy to turn on/off, etc.

are there any git config options that could be used to inform what to do here?

push.autoSetupRemote and push.default are what git uses today for this.

[arxanas]

To make this safer, it might be interesting to have a "user prefix"

I'm in favor.

If you're using GitHub or another hosted platform, you could also query the API to find the currently-authenticated username and use that as a prefix. (You could use the current username, but I don't like defaulting to that, because it's often not the name I want to be associated with online. The current Git identity might be sensible in some form.)

[epage]

Since GitHub by default take a n:1 approach, it seems like we should accommodate that by default, and have users opt into a 1:1 workflow with some kind of configuration setting. We could also auto-configure the default behavior of the remote based on whether we think it's GitHub or GitLab, etc.

Besides a question of defaults, the fact that you would be implicitly generating branch names (assuming the user is on a branch) would be reason enough to make n:1 the default

[claytonrcarter]

Would it make any sense to be able to use revsets to determine which commits should be grouped into branches for pushing? So if I'm on a stack w/ commits A though E, I could do something like git submit A B:D E to create three branches: one for just A, one for B, C, D and one for just E. (Assuming the sets are connected and not-overlapping, I guess.)

That said, I'm still not familiar w/ the workflow in question, so perhaps that wouldn't be helpful. I have always been happy to build a stack of commits and then sprinkle my own branch pointers into it once something feels mature enough to push.

[slymon99]

• By default, the branches to push are those in stack(). Is that a reasonable default, or is . a better default and the user should have to explicitly write/alias something to push branches in thr current stack?

I think always push the whole stack, that's sort of the point of the command, if you want to push . you can just git push -f

Branches which have no upstream are not pushed. You have to pass --create to do so. Is this sensible? I vote yes, since it's a somewhat side-effectful operation. But, then again, so is force-pushing branches at all.

All branches have to be explicit created by the user.

I think a configuration option makes sense here. I think the two options should be

• [Probably default since its more what people are used to] branchstrategy = manual

  • Branches need to be created manually
  • Don't create a remote branch automatically
  • Force push whatever branches already are created + have remotes

• branchstrategy = stackedcommits

  • Create ephmeral branch names that are some combination of a git branchless identifier, stack identifier (either number or date), user who created, and commit number on the stack (this is important for making PRs and asking to merge into the prior commit)
  • e.g. ephemeral-gb-stack127sclark-03
  • there are some questions here about what you do if you re-order commits (do you recreate branches?) - I typically find that if you are re-ordering commits you are fine losing your PR feedback anyway. Maybe you want to just include a hash instead of a number

• ideally some extension with github cli / other code review cli's to automatically create PRs.

  • automatically set up the correct parent branch to merge to and have the PR text start with NEXT PR [link] PREV PR [link] (or actually have every PR in the stack linked as well)
  • edit PR titles to have [3/5] automatically
  • have one tag that goes on every PR base (commit 0) and one tag that goes on every other PR (commit 1-n) so that people can filter out non-base commits (usually you want to just see base commits and then browse your way up the stack with the navigation within)

[slymon99]

this second piece is a pretty massive feature, but that's at least my personal dream

[black7375]

I think it would be nice to have a checking method for stacked branch.

Sample

Goal

• Open pull request with three stacks in feature branch
  • Feat C [1/3](3a05375e)
  • Feat C [2/3](28baf953)
  • Feat C [3/3](882b958c)

# https://github.com/arxanas/git-branchless/wiki/Workflow:-divergent-development#backtrack-as-necessary
$ git prev 2
$ git sl
⋮
◇ e6adfe90 9d (main) Main branch commit
┃
◯ b91eec5c 5m A
┃
◯ 666b4b9e 5m B
┃
◯ 3a05375e 5m (feature) C - stacked 1
┃
● 28baf953 4m C - stacked 2
┃
◯ 2dfed453 1m C - stacked 2 with more commit
┃
◯ 882b958c 1m C - stacked 3

Step

The example below included an implicit api and an explicit api. (I don't know what api you like)

0. Start [explicit api]

• git stack start (current branch)
• git stack start feature (branch name)
• The first commits of the branch can be created automatically.

1. Marking

• Multiple: git stack 3a05375e 28baf953 882b958c
  • git stack add 3a05375e 28baf953 882b958c [explicit api]
  • commit hash, gitrevisions and revset can be used
  • All commits can be marked git stack "*" or git stack --all
• Each
  1. git checkout 3a05375e && git stack (optional)
     • The first commits of the branch can be created automatically
  2. git checkout 28baf953 && git stack
  3. git checkout 882b958c && git stack

2. Create stacked branch [explicit api]

• git stack end
• create feature-2, feature-3 branch

3. Submit

• git stack submit
  • target branch and title are automatically created
  • The default value of target branch is main(master) branch
  • The default value of title is stack's branch name or first line of stack's first commit message
  • Detect remote url (github, gitlab, ..etc)
• git stack submit main (Specify branch)
  • or git stacdk submit --branch main
• git stack submit --title "Feat C [{INDEX}/{TOTAL}]"

To sum up, it's as follows.

## Implicit api - multiple marking
git stack 3a05375e 28baf953 882b958c # 3a05375e can be omitted
git stack submit

## Implicit api - each marking
git checkout 28baf953 && git stack
git checkout 882b958c && git stack
git stack submit

## Implicit api - each commit marking
git stack "*"
git stack submit

# Explicit api - multiple marking
git stack start # Start from 3a05375e
git stack add 28baf953 882b958c
git stack end
git stack submit

Manage

• Unmark stack
  • git stack reset <commit_hash>
• Cancel all tasks
  • git stack abort
• Show stacked list
  • git stack list or git stack status
  • Can be tracked merged stack, stacked commit, unstacked commit

[arxanas]

Thanks for your input. I think in general, we want to avoid stateful multi-part commands (the explicit API). It would probably be better to start a stack using the implicit API and have a way to add more commits to the stack in a single command.

Also, the name git stack would trample on https://github.com/gitext-rs/git-stack, which you might be interested in.

[black7375]

I also think implicit API is better.
@epage is Collaborator, so it would be nice if it could be managed by merging upstream into this repository.

If not, We can do it like git submit set or git submit add.
In any case, my opinion is that I need control of stack generation.
There is no strong opinion on the rest. (I think stack() and explicit -create of RFC are reasonable defaults)

[epage]

git stack is a separate command that is an alternative to git branchless.