Documentation enhancements

[arxanas]

• [x] README: Put installation at the top/make it easier to get started
• [x] README: Mention that it scales to large monorepos.
• [x] README: Add a link to the lightning-fast rebase demo.
• [ ] README: Once git undo has a non-interactive mode, add an inline-playing demo to the README, so that the user doesn't have to visit another page to view the demo.
• [x] README: Call out speculative merging as a major feature.
• [ ] Finish unfinished workflow documentation items:
  • [ ] Stashing
  • [x] Divergent development
• [ ] Possible new workflow documentation items:
  • [ ] Making commits
  • [x] Editing an old commit's contents
    • Done in https://github.com/arxanas/git-branchless/wiki/Workflow:-Editing-an-old-commit's-contents
  • [x] Editing an old commit's message
  • [ ] Reordering commits
  • [ ] Creating branches
  • [ ] Updating branches
  • [ ] Adding a commit to a stacked branch (see https://github.com/arxanas/git-branchless/discussions/315)
  • [ ] Syncing branches with a Github pull request
  • [ ] Deleting branches
  • [ ] Updating local work on top of the remote main branch
• [x] Add documentation about git next/git prev --all/--branch flags.
• [x] Add documentation for git amend command.

[bcongdon]

+1 for docs relating to "updating local work on top of the remote main branch". Merging a PR and then rebasing the local branchless commits onto the new state of the remote branch was unintuitive the first few times I went through that process

[arxanas]

@bcongdon what was your workflow then vs now?

[bcongdon]

Now, I run git fetch and git rebase origin/main, and resolve any conflicts. I still run into issues occasionally with (local) branch pointers becoming out of date, and I have to sometimes do additional git move's to update my subtree.

In a previous (mercurial) workflow, this was handled a bit gracefully with a catchall "sync" command, which implicitly pulled and rebased my local commits onto the trunk branch commit.

I bet my current git-branchless workflow is suboptimal though, so docs around best practices for syncing to a remote repo would be helpful (even if the docs aren't necessarily prescriptive)

[arxanas]

@bcongdon I hope to release a git sync command soon. In the meantime, I recommend that you use git move -d origin/main rather than git rebase origin/main, as it should behave uniformly better.

[terinjokes]

fwiw, git move -d origin/main doesn't seem to work if there are currently no commits on the stack, as it instead tries to create a cyclical loop. I'm used to running stg pull -m which handles both cases.

[arxanas]

@terinjokes what is the behavior of stg pull -m in that case? Does it just produce a no-op message?

[terinjokes]

It's a noop if the local branch and the remote branch have no differences. Otherwise it effectively fast-forwards to match the remote branch.

[claytonrcarter]

@arxanas I took the liberty of writing up a wiki page for git reword: https://github.com/arxanas/git-branchless/wiki/Command:-git-reword

Please edit however however you like, or tell me what you'd like to see changed and I can work on it.

[arxanas]

@claytonrcarter Much appreciated, it looks great!