Suggestion: Include magit in Appendix A

[equwal]

Hello,

I've been using Magit in Emacs for a couple years now, and I can say that it is the way to do it from Emacs.

If I had been able to access a section on Magit when I was getting started, it would have been easier to get over the initial learning curve. Currently the only resource I know of for Magit is the documentation itself.

There are a few "gotchas" that come withh it also, like trying to figure out how to do a rebase/squash effectively. Even just mentioning it somewhere would be cool.

[HonkingGoose]

Hi @equwal,

Have you seen https://git-rebase.io/ yet? That taught me how to use git rebase properly. It walks you trough a sandbox of examples of rewriting history with git rebase. I really, really recommend you read and do the exercises listed at that website! 😄

I agree that the documentation for Magit rebase alone probably won't teach anybody how git rebase is supposed to work, but that probably also isn't the intention of the Magit documentation.

Also a handy tip from the git-rebase.io website:

Tip: your local master branch evolves independently of the remote master branch, and git stores the remote branch as origin/master. Combined with this trick, git rebase -i origin/master is often a very convenient way to rebase all of the commits which haven't been merged upstream yet!

[equwal]

I agree that the documentation for Magit rebase alone probably won't teach anybody how git rebase is supposed to work, but that probably also isn't the intention of the Magit documentation.

Fair enough. With some experience using Magit it looks more and more like my confusion came from misunderstanding git, and then being unable to use Magit effectively for that reason.

[HonkingGoose]

But it still might be a good idea to add a section mentioning Magit in the ProGit2 book. The maintainers of the project haven't yet chimed in with their thoughts.

So maybe you shouldn't close the issue yet, until the maintainers have had their say?

It wasn't my intention to pressure you into closing this issue, I just wanted to help you understand git rebase. 😄

[equwal]

But it still might be a good idea to add a section mentioning Magit in the ProGit2 book. The maintainers of the project haven't yet chimed in with their thoughts.

So maybe you shouldn't close the issue yet, until the maintainers have had their say?

It wasn't my intention to pressure you into closing this issue, I just wanted to help you understand git rebase. smile

Fair enough.

[HonkingGoose]

Summary:

Given all that I say below, I recommend adding a [NOTE] or [TIP] that mentions Magit, and link to the Magit manual. But leave documenting Magit where I think it belongs: with the upstream maintainers/contributors to the Magit program.

I'll of course be happy to make a pull-request for the tip or note, if the maintainer wants me to. What is your view/decision on this @ben?

On Magit rebase documentation:

I see that the Magit manual has a chapter on rebasing, which covers the rebase commands, and helps with the rebase steps (see the 2 pages right after the introductory page on rebasing). I think the unclear rebase docs should be fixed upstream at the Magit manual project, and not in this book.

About adding general Magit tips/tricks/help to this book:

I have opened a issue to discuss how much Git editor integrations should be in the book. One of the goals the author of the book has stated is:

I'd still like some basic-overview material here for the most popular editors (preferably in evergreen fashion), but with pointers to more extensive manuals where available. What we have is too heavy and hard to maintain, but none isn't enough editor-integration content for this book IMO.

Userbase for Emacs and Magit:

I would argue that Emacs (and Magit) are not among the most popular editors according to this 2019 stackoverflow survey on development tools, as you can see Emacs is used only by 4.5% of developers. Vim has 25.4% of developers using it for comparison to a similar CLI text editor.

Maintenance concerns:

Also it would be hard for most contributors to cover Emacs and Magit, as they are likely not users of those programs. Nobody has offered to create such a section to the ProGit2 book. Also I think that the basic usage of Magit is covered at Magit Getting-Started manual.

[equwal]

Userbase for Emacs and Magit:

I would argue that Emacs (and Magit) are not among the most popular editors according to this 2019 stackoverflow survey on development tools, as you can see Emacs is used only by 4.5% of developers. Vim has 25.4% of developers using it for comparison to a similar CLI text editor.

I'd take those statistics with a grain of salt. What percentage of readers of Pro Git use Emacs is what matters, and I suspect that Notepad++ users aren't a major part of the audience.

That being said, I've moved away from Emacs toward CLI use, but magit is still a very nice program and probably the #1 thing I miss from Emacs.

[salewski]

On 2020-08-28 09:32:27, Spenser Truex spake thus:

Userbase for Emacs and Magit:

I would argue that Emacs (and Magit) are not among the most popular editors according to this 2019 stackoverflow survey on development tools, as you can see Emacs is used only by 4.5% of developers. Vim has 25.4% of developers using it for comparison to a similar CLI text editor.

I'd take those statistics with a grain of salt. What percentage of readers of Pro Git use Emacs is what matters, and I suspect that Notepad++ users aren't a major part of the audience.

That being said, I've moved away from Emacs toward CLI use, but magit is still a very nice program and probably the #1 thing I miss from Emacs.

I, too, would take those stats with a huge grain of salt. Emacs and vi are mainstays on Unix-like systems, regardless of what shows up in a popularity contest^W^Wsurvey. I'm typing this message in GNU Emacs.

[salewski]

On 2020-08-28 06:59:11, HonkingGoose spake thus:

Summary:

Given all that I say below, I recommend adding a [NOTE] or [TIP] that mentions Magit, and link to the Magit manual. But leave documenting Magit where I think it belongs: with the upstream maintainers/contributors to the Magit program.

+1

[ben]

I've heard great things about Magit, although I was never able to internalize its incantations when I was an EMACS user.

I'd definitely consider a PR that adds a small section to Appendix A. Magit seems pretty stable, so probably most of what's described won't get out-of-date very fast.