Tutorial compared with stock git flow

[black7375]

First of all, thank you for making a great tool.
In my opinion, if there is a additional tutorial for the onboarding of new users, it will be helpful.

The current Tutorial documentation explain key features well. 👍
However, users who are familiar with stock git branch strategies seem to have difficulty switching or applying them right away. #402

I think it would be nice to explain the way that comes from a relatively universal git flow or github flow in the following way:

1. Description of mental model through comparison
2. Examples that compare and practice step by step
   • Make one feature & reflect to main
   • Make multiple feature & reflect to main
   • Merge with conflict
   • Pull & push related work
3. Brief description of additional workflows (Divergent development, Stashing..)

[arxanas]

That's a good idea! Unfortunately, I don't have time to work on the documentation right now, but I would be happy to accept or review documentation towards this end if anyone else wanted to write it.

[black7375]

I also don't have time right now, but I will try document work if possible by early next year.

[black7375]

Hello?
Recently, I have a chance to introduce this tool to team members who use GIT and briefly documented.
I intentionally used a lot of screenshots and I think it will help new users. #778

The purpose of this document focuses on how to maintain a linear branch(branchless) using the command of Tutorial.

If you like it, I hope it will be added to the wiki.
The current tutorial document is good as a summary.

---

Learn step by step

Init

First, we will initialize and create a general branch.

• Initialization with git init and git branchless init
• After commit0 ~ commit2, make a branch called featA and proceed with commit3, commit4
• Returning to main

git init --initial-branch=main
git branchless init --main-branch=main

touch commit0
git add commit0
git commit -m "Add: commit0"

touch commit1
git add commit1
git commit -m "Add: commit1"

touch commit2
git add commit2
git commit -m "Add: commit2"

git switch -c featA
touch commit3
git add commit3
git commit -m "Add: commit3"

touch commit4
git add commit4
git commit -m "Add: commit4"

git switch main

As you can see from the log, it runs through git hook.

Let's check the created commits by git log.

git log --graph --oneline --all --decorate --color --topo-order --branches -10 | tac

Let's also check with git sl(git smartlog).
It makes information easier to see with simple command.

git sl

Basic to use

You will now create an anonymous branch.
You can see that they are both tracking well.

touch commit5
git add commit5
git commit -m "Add: commit5"

git switch --detach # Start anonymous branch

touch commit6
git add commit6
git commit -m "Add: commit6"

Now let's say you want to go back to main, the previous commit. What should you do?
If it was stock git, it would have been called git switch main, but here is enough with git prev.

git prev

On the contrary, you can use git next to switch to the next commit.
If you put the number like prev 3, you switch to before 3 commits.

git next
git prev 3

Moving commits

Now, the main next is commit6.
But you might want to make commit3 and commit4 coming after main.
That's what it takes to keep a commit histoy linear.

Using git sync becomes a rebase based on main.
Let's switch to commit3 and run it.

git next 2 -o # Go to the old commit direction, The new commit direction is `-n`
git sync

What if you regret after doing this?
It can be returned to the magic spell, git undo.

git undo

Here comes one more advantage of git sl.
It is that it only tracks meaningful anonymous branches!!
In fact, I forgot the screenshot and turned it back to git undo, but it's dirty when you look at the original commit log graph.

(commit3 and commit4 are shown three times.)

This time, let's move commit6 back to commit4.

git move -s 7de4f31 -d d4b489a

After git undo, you can also move the featA branch, commit3 and commit4, to commit6.

git undo
git move -b featA -d 7de4f31

Keeping it branchless

With git-branchless, it is this easy to keep the commit graph without branch.
But when I thought about it, I wanted to rebase commit6 and commit3.

git rebase -i HEAD~2

A branch has been created because a new commit is created.
Fortunately, the git restack command in the guide will solve it neatly, so don't worry.

git restack

git restack can be applied not only to git rebase but also in git commit --amend.
If there is a conflict with git sync or git move, it fails to explicitly add the --merge option, and you can always use git undo if you want to go back while merge.

Now enjoy a simpler and smarter commit graph, a fearless git commands and commits.

There is also a stronger and more intuitive revset than revision, so check if you need a selector.

[arxanas]

@black7375 Thank you very much! I linked to this post in the first paragraph of https://github.com/arxanas/git-branchless/wiki/Tutorial.

By the way, you can replace

echo "main" | git branchless init

with

git branchless init --main-branch=main

[black7375]

Thank you for advice 😄