Discussion post: Remove section on Git with External editors wholesale

[HonkingGoose]

Hi @ben,

I was wondering about your current view on this matter. I noticed you said in #1144:

I see an argument for including all editors who want to be here, since we want to be useful, but that's a ton of work. I also see an argument for removing all the editor-specific content altogether, since we don't want to be out-of-date. In the end, for the sake of cohesiveness and continuing quality, we have to be selective in which editors we have sections for. I'm going to close this PR, and set up an issue with the editors we do want to support.

I myself, am firmly in the camp of removing all the editor-specific content at
https://github.com/progit/progit2/tree/master/book/A-git-in-other-environments/sections, and only have a list of links to the docs that the code-editor/IDE team themselves have made on using git with that editor.

That way we would only have to maintain the links to the docs. This would decrease the maintenance burden on the contributors/maintainers. It also reduces the "surface area" of things that a ProGit2 maintainer/contributor needs to know about.
I think that a contributor to the ProGit2 project should have to know about 2 things only: Asciidoctor and using git via the terminal.

Most editor teams have made their own git tutorials/documentation anyways, that are really good, at least in case of well used editors like the Jetbrains suite, VS Code or Visual Studio.

I'll expand this post with evidence to help see the current status of support for git within different editors.

---

Evidence in favor of removal:

Exhibit 1 Jetbrains IDE's (Check the sidebar):
https://www.jetbrains.com/help/idea/version-control-integration.html
Contains help on:

• Enabling version control
• Managing files under version control
• Compare file versions
• Resolve conflicts
• VCS integration with issue trackers
• Manage changelists
• Shelve and unshelve changes (git stash git apply)
• Use patches
• Review changes

Exhibit 2 VS Code:
https://code.visualstudio.com/docs/editor/versioncontrol
Contains help on:

• SCM providers
• Git support
• Commit
• Cloning a repo
• Branches and tags
• Remotes
• Git status bar actions
• Gutter indicators
• Merge conflicts
• Viewing diffs

Exhibit 3 Visual Studio
https://docs.microsoft.com/en-us/visualstudio/windows/?view=vs-2019
Click on section "Version control" this leads to https://docs.microsoft.com/en-us/azure/devops/repos/?view=azure-devops where you can find tutorials on how to use git within Visual Studio.

---

Evidence against removal:

Exhibit 4 Atom:
https://flight-manual.atom.io/using-atom/sections/version-control-in-atom/
Atom's documentation is on the light side compared to the docs for VSCode and Jetbrains, as it assumes that you already know how to use git.

Contains help on:

• Checkout HEAD revision
• Git status list
• Commit editor
• Status bar icons
• Line diffs
• Open on GitHub

Exhibit 5 vim:

To my knowledge vim has no official documentation on how to use git within vim. So here it would be helpful to have a section on how to use git within vim.

Exhibit 6 emacs

Emacs itself doesn't seem to have any official documentation, that I could find with a quick search. However the magit interface is very popular, and they have docs here:
https://magit.vc/manual/magit/

---

Summary:

Well what do you know, more evidence has changed my opinion a bit. Beforehand I though, just remove it wholesale, but for some editors it would be helpful to have a section, like with Vim or Emacs perhaps.

Still we cannot compete with the docs for really popular editors, like the Jetbrains suite, VS Code, Visual studio.

I still think a clear separation of concerns would be good:

• ProGit2 team: explain git basics, git on the terminal, git fundamentals, etc.
• Code editor team: make docs for their git integration.

I just want to say, I like the ProGit2 book very much, and I like contributing to it. So this is in no way a putdown of the hard work that you and others have put into this section in the first place!

Postscript: I'm sorry for the mess I made in between... 😞 I pushed the button too soon on creating the issue. So I'm sorry for the repeated edits. I'll stop editing this issue now, so that you can review it proper! 😄

[ben]

Yeah, I think you've got it about right. When this was published in 2014 (and even more so with 1e in 2008), the documentation available for using Git inside the various editors was sparse, and since we knew we'd be shipping straight to the Git website, we wanted to provide at least a basic overview for the most popular editors. That's where many people will first encounter Git, so this book would be more useful if we helped with that experience.

The landscape has changed a bit since then, and this book is no longer more comprehensive than other resources, especially since editor integrations have become more complete and sophisticated.

I think we agree in principle, but I differ with you a bit as to where the line should be drawn. 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.

[HonkingGoose]

Yeah, I think you've got it about right. When this was published in 2014 (and even more so with 1e in 2008), the documentation available for using Git inside the various editors was sparse, and since we knew we'd be shipping straight to the Git website, we wanted to provide at least a basic overview for the most popular editors. That's where many people will first encounter Git, so this book would be more useful if we helped with that experience.

Thank you for confirming that I'm not totally barking up the wrong tree! And I agree, if the external docs are sparse, then we should at least provide basic help.

The landscape has changed a bit since then, and this book is no longer more comprehensive than other resources, especially since editor integrations have become more complete and sophisticated.

Agree!

I think we agree in principle, but I differ with you a bit as to where the line should be drawn. 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.

It's nice that we're not having a major clash of ideas here! 😄 😌

[HonkingGoose]

I think we agree in principle, but I differ with you a bit as to where the line should be drawn. 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.

I'm closing this issue, as the original question: "Should we have a section on Git with external editors at all?" has been answered by the project maintainer.