Documentation

[amardeep]

TLDR: It would be great to improve documentation.

I have not used phabricator or other tools like that. In our team, we follow master based development, linear history (no merge commits). But we are often working on multiple features in parallel. As such, just using git-stack --push and git-stack --pull is a godsend. So thank you :) But without having any context of other such tools/processes, it is hard to follow the documentation. For eg:

• What is protected branch? What it should be (I could guess, but would be nicer to elaborate more)
• WIP: Would be nice to elaborate - what prefixes could be used - what happens when it is there.
• In Using section, there is a comment # To push whats ready. But what's considered ready
• Examples in the FAQ section - I am totally lost - can't understand them :(
• git switch -v feature2 - I couldn't find -v flag for git switch (Maybe just a typo for -c)
• In faq "How do I add a commit to a branch (PR)?". Normally, I am working on a branch, and
  I just add commits on top of that branch. Here it says I have to use git rebase -i. Now I am
  wondering if by not using rebase I will break it. Or maybe you mean that if you want to move
  commit to a different branch - then there is no extra support - just do what you would have done
  and rebase.
• In "How do I start a new feature?", it says git switch feature1 && git switch -c feature2. Again,
  I am confused why is git switch feature1 required. If I want to add feature on top of current changes,
  I would use git switch -c feature2. If I want to work on the feature as independent feature, I use
  git switch -c feature2 origin/master --no-track. If I were to adopt branchless workflow, perhaps I
  wouldn't worry about branches at all until I was ready to send for review.
• What does git-stack --rebase really do and in which scenarios it should be used.

[epage]

What is protected branch? What it should be (I could guess, but would be nicer to elaborate more)

The definition got moved to "Examples". This should be in a more clear place

Parent branch auto-detection works by separating the concept of upstream-controlled branches (called "protected branches") and your development branches.

[epage]

Overall great feedback! Thank you for this!

[epage]

Mind looking over the docs again? I'm wondering how much my changes help and where they could use more attention

If you want to specifically see whats changed

• epage@4d12a7d
• epage@7687724

[epage]

One thing I can see being added is an overview of the concepts, like I did in arxanas/git-branchless#125 (comment).

Created https://github.com/epage/git-stack/issues/105

[amardeep]

These changes are very useful. Thanks.

Rewording faqs help a lot. First faq "How do I stack another branch on top of an existing one?" is still confusing for me - mainly as I don't understand what git-stack --rebase does. It would really help to have a separate section on that. Also in git-stack --rebase --base HEAD~~ --onto feature - is it supposed to be feature or one of feature[12]? Also, two bullet points are the same - "Moving existing". Do both need to be done or are they alternatives (I suspect once i understand what git-stack --rebase is doing it will make more sense)

What you have already is good enough for me, though i feel it would be nice if git-stack --pull and git-stack --push (also --rebase? ) had their own sections. Perhaps taking some content from post on git-branchless and docs/comparison.md. I think the content in comparison.md where you compare with raw git is very useful, and would be better if present in main README. It gives a better sense of what these commands are doing internally (as equivalent git concepts) and why it is worth using them.

Also, another section worth considering is if anything special should be done to uninstall it - does it keep some files in .git which could be deleted etc.

[epage]

" is still confusing for me - mainly as I don't understand what git-stack --rebase does. It would really help to have a separate section on that

The second commit included that but I've expanded it further, including yoru idea of moving the raw git comparison to it

See https://github.com/epage/git-stack/blob/main/docs/reference.md#commands

Also in git-stack --rebase --base HEAD~~ --onto feature - is it supposed to be feature or one of feature[12]? Also, two bullet points are the same - "Moving existing". Do both need to be done or are they alternatives (I suspect once i understand what git-stack --rebase is doing it will make more sense)

I've updated it to:

• New branch: git switch feature1 && git switch -c feature2 and start adding commits
• Moving existing: git stack --rebase --base feature1 --onto main moves feature2 to main, from off of feature1
  • Without git stack: git rebase feature1 --onto main

Also, another section worth considering is if anything special should be done to uninstall it - does it keep some files in .git which could be deleted etc.

Huh, hadn't thought of this because git-stack is pretty mundane in this way. The only files we leave behind are the backups, and we cap how many backups we maintain. I've added

Uninstall

See the uninstall method for your installer.

Once removed, git-stack leaves behind:

• .git/branch-stash

Removing this is safe and will have no effect.

[amardeep]

Wow, all these changes look really good :) Especially the reference page. Thanks.

[epage]

Thank you! This feedback has been great!

[uloco]

Having also never worked with a branchless or stacked workflow myself, I am not quite sure how I should work with this tool. Especially if the rest of the team is still using a feature branch strategy with code reviews. It would really help if you could add more documentation in general, when to use it and what to achieve, what workflow you follow in your day to day work with it. Maybe some videos / screen casts would help a lot to get an overall understanding what this tool helps me in doing and what it doesn't.

I am constantly asking myself if I am doing this correctly, when to pull / push / rebase etc.
I have a long lived branch that is a migration, should I protect this also since a lot of branches are going into this? (for example)
If you have a good reference on this topic in general, feel free to share :).

I read the article in the Readme about the branchless workflow and it sounds great but I am at not point where I can convince my team to switch full on, so I need a more "we are using a standard branch workflow, what can I use this tool here for" point of view.

[epage]

I am also not quite sure which of the both commands --repair and --rebase I should use in which scenario. It should rebase / repair on pull automatically right?

--pull implies --rebase. --repair is meant to be used after a manual operation messes up your stacks in an attempt to try to fix your stacks. I wonder if --fix might be better :).

[uloco]

So what's the difference between --rebase and --repair then? When do I need to run which?
Do i need to run --rebase or --repair when I manually commit to a parent branch for example?
Do I need to run --rebase or --repair when I pull manually without git stack --pull?

[epage]

--rebase does just that, rebases all of your branches onto the target branch.

--repair is meant to patch up manual rebase operations. For example, git stack --rebase doesn't stop to allow resolving conflicts but stops part way. You then might have to use git rebase to resolve things. This could lead to your stack being split into two. --repair is a series of heuristics to help in situations like this to try to restore stacks.

[uloco]

I thought git stack --rebase would also rebase all my branches for commits in the main branch (and also descendants) but it does only for the current branch I am on. I guess this is what confused me most.

So when I have a main branch, add two commits, then branch from there, add two commits and again branch from there and add some commits. When someone changes something in main and i do git stack --pull it updates all branches. But when I commit directly to main and do git stack --rebase i have to check out every branch myself. I was expecting it to behave like pull...

[epage]

Say you have

• 123 upstream/main
• 234
• 345 main
• 456
• 567 A
• 678
• 789 B

Adding a commit to main is like adding a commit to A. When we rebase, we do not know what you had intended and don't guess. This is where --repair comes in.

With that said, generally our support for developing directly on main is pretty weak and subject to change and/or breakage (it might have stopped working in the last release) While I try to keep it in mind, I'm not likely to make it a focus because I personally have found it to be problematic and find it best to always be working off of a branch. If people want to share how it benefits their workflows so I can better understand other use cases, then I'm more open to putting more work into it.