Documentation

[epage]

Discussed in https://github.com/epage/git-stack/discussions/100

^{Originally posted by amardeep October 20, 2021}
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.