Add git rebase -i [SHA1] example.

[HonkingGoose]

Which version of the book is affected?

Problem is present in source and online books.

Describe the bug:

The book does not explain how to select the correct SHA1 commit to start a rebase operation on. The book has no example for the git rebase -i [sha1 of specific commit] command.

Steps to reproduce:

1. Go to https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History or https://git-scm.com/book/en/v2/Git-Branching-Rebasing.
2. Neither of them mention the git rebase -i [sha1 of specific commit] command.
3. Reader is not sure how to select the correct commit hash to start rebasing on.

Expected behavior:

1. Book contains a section on the git rebase -i [sha1 of specific commit] command.
2. Book explains how to select the correct starting hash to rebase on.
3. Book gives a guided example like the ones used for git rebase -i HEAD~3.
4. Book explains methodology behing selecting the correct commit to rebase from.

Screenshots:

Additional context:

The git documentation(https://git-scm.com/docs/git-rebase#_interactive_mode) has some guidance:

Start it with the last commit you want to retain as-is:

git rebase -i <after-this-commit>

Desktop:

• Operating system: Ubuntu 18.04.2 LTS
• Browser/application: Firefox
• Browser/application version: 66.0.2

[HonkingGoose]

Following on from my git rebase headaches from #1244

@ben seems to have a nice workflow, maybe we should try adding that into the book? It skips figuring out the correct SHA1 hash to start from atleast... 😄

Ben's workflow:

The other way you'd do a rebase looks like this, which sounds like a lot but isn't that bad once you've done it 3 or so times:

1. Fetch from the remote that represents this repo (`git fetch upstream`)

2. Start an interactive rebase on the newly-fetched master (`git rebase -i upstream/master`)

3. In the resulting editor, change every occurrence of `pick` _except the first_ to `fixup` (or `f`)

4. Change the first `pick` to `reword` (or `r`)

5. `:wq`

6. The next editor is for the final commit message. Change the contents to something reasonable and `:wq`

Again, that sounds hard, but if you've done it before it's not so bad, and the results are rather nice.

[aollier]

From https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History:

For example, if you want to change the last three commit messages, or any of the commit messages in that group, you supply as an argument to git rebase -i the parent of the last commit you want to edit, which is HEAD~2^ or HEAD~3.
It may be easier to remember the ~3 because you’re trying to edit the last three commits, but keep in mind that you’re actually designating four commits ago, the parent of the last commit you want to edit:

$ git rebase -i HEAD~3

I put in bold the information about the commit you must provide to the git rebase -i command.
You simply must pass the parent of the commit you want rebase from. Is not it clear enough?

[HonkingGoose]

Hi @aollier,

Thanks for responding. 😄 I've chunked this comment into separate sections, I hope this is readable for you.

---

Executive summary of proposed changes:

1. Add the git rebase -i command from the git manual.
2. Add text that clearly explains "parent of commit".
3. Add a sane, "batteries included" workflow for rebasing, with clear examples/guides.

Now I know this is getting way outside of the "one clear, actionable bug per report" territory.

Do you want me to file 2 new issues (for point 2 and 3 of the list above)? And continue the conversation in their respective issues?

---

On git rebase command:

Current text:

"you supply as an argument to git rebase -i the parent of the last commit you want to edit,":

1. I need to know what a "argument" to a command is. (this is not a really big deal, but it's programmer language, instead of normal people language)
2. Command to use: git rebase -i
3. "the parent of the last commit you want to edit", this is a lot to unpack in just a few words.
4. I still don't know where to start rebasing from. 😕

The current text only has a fully explained example for git rebase -i HEAD~3 usage.

Git manual explanation:

Start it with the last commit you want to retain as-is: git rebase -i <after-this-commit>

1. How to pick the right commit to start from.
2. Command to use git rebase -ibut also the argument <after-this-commit>, so it's more specific.
3. I might actually succeed following that instruction. 😄

---

On parent of a commit terminology in the Pro Git book:

I've tried searching for parent in the progit2/master source, and I'm not really finding anything, that to me, explains definitively how parent/child works in git. I think the most relevant hits of parent are:
These links all contain the word "parent"
https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell

When you make a commit, Git stores a commit object that contains a pointer to the snapshot of the content you staged. This object also contains the author’s name and email address, the message that you typed, and pointers to the commit or commits that directly came before this commit (its parent or parents): zero parents for the initial commit, one parent for a normal commit, and multiple parents for a commit that results from a merge of two or more branches.

https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging

Instead of just moving the branch pointer forward, Git creates a new snapshot that results from this three-way merge and automatically creates a new commit that points to it. This is referred to as a merge commit, and is special in that it has more than one parent.

https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging

The -m 1 flag indicates which parent is the “mainline” and should be kept. When you invoke a merge into HEAD (git merge topic), the new commit has two parents: the first one is HEAD (C6), and the second is the tip of the branch being merged in (C4). In this case, we want to undo all the changes introduced by merging in parent #2 (C4), while keeping all the content from parent #1 (C6).

---

On including a sane workflow:

Now that the whole "specific git commit to use for rebase" and "parent terminology" has been covered. I would like to propose that the book include a workflow that skips that whole "select correct sha1" process altogether. I'm looking for some "batteries included" workflows so to speak.

I hope I'm not the only one struggling with the git rebase workflow, and I hope that improving the book with some workflows helps other readers too. 👍

---

Thank you for your time, and for reading this.