Add a section on how to use git

[jyn514]

Git is a major part of contributing to rust-lang/rust, but it sees almost no discussion in the guide. There should be instructions on:

• How to pull, branch, push, etc. This can just be a link to a git tutorial, but it should be there. It should also have basic instructions on GitHub (even if it's just 'the create pull request button is here').
• How to rebase. A lot of people are afraid of rebasing if they haven't used it a lot: the commands are not intuitive, it's rewriting history which already sounds scary, and you run into merge conflicts as you go which make the whole thing even more painful. There should be a detailed walkthrough on this.
• The no-merges policy. This is really discouraging to newcomers: they have a change that works, but it's not accepted because of what seems like paperwork. It should say why we have this policy and how to fix your PR if you made a merge by accident.

Writing this requires no knowledge of rust or the compiler (although having made PRs to rust-lang/rust is a bonus). It should go in the 'Contributing to Rust' section, possibly in its own page.

[jyn514]

Possibly there should be instructions on how to do this in a GUI too, but I've never used a git gui for rebasing and I wouldn't be able to help with that bit.

[workingjubilee]

People should be reminded that making a branch is effectively free in git, so it's fine to just pop over to another branch to save their workstate and then pop back. I cheat by just reaching back in history through the reflog if I screw up but... who even has heard of the reflog?

[jyn514]

'Git tips' would also be a useful section (maybe near git worktree in the suggested workflows page?) but I see it as something separate from this issue, which is 'how do I contribute at all'.

We should mention how to fix issues from adding a submodule by accident though: rust-lang/rust#75949 (comment)
Maybe we should also suggest git add <file> instead of git add .? That would help prevent committing submodules in the first place.

[workingjubilee]

Right, I mean that as a heads-up before rebasing. "rebasing sounds intimidating but you can make an additional branch, push it to your fork on GH or whatever, and guaranteed you have your work saved."

Yeah, people should be adding by-file, or at least by-specific-directory, in a deliberate fashion, not git add ..

[workingjubilee]

Graphical Git UIs are always going to be a case-by-case for each, so covering rebasing in any of them will require someone who actually has used that tool, or finding other people's tutorials. However, many people lean on VS Code as a dev tool, and since VS Code is semi-officially-supported by rust-analyzer, so we should probably lean on assisting people with VS Code's support for git, as a start.

[spastorino]

Niko showed https://devguide.python.org/ to me and found that there are some things about git there. Maybe we can use some inspiration from their devguide :)

[jyn514]

Hmm, that's mostly just branching - I'd like to cover rebasing in more depth. It's a good start though :)

[spastorino]

Yeah I didn't carefully look at it, I was just guessing that there may be some good content there :). Still something that may inspire some of our things in the guide :).

[jyn514]

Another good section would be how to squash commits (related to #824, but with less setup preferably).

[guswynn]

I found https://rustc-dev-guide.rust-lang.org/building/suggested.html#working-on-multiple-branches-at-the-same-time to be extremely valuable, adding more stuff about git usage would be great! (also, I know somewhere in the guide it talks about the style around squashed vs unsquashed commits, but reiterating that in a dedicated git section would be awesome)

[jyn514]

In the meantime, @GuillaumeGomez has a great blog post about this here: https://blog.guillaume-gomez.fr/Git-tips/1/1

[GuillaumeGomez]

@jyn514 If you talk about squashing commits, it's https://blog.guillaume-gomez.fr/Git-tips/1/2 ;) (and thanks for linking to it!)

Although I wrote those tutorials mostly for rust contributors so I guess all chapters are applicable.

[camelid]

Yeah, VS Code has decent interactive support for resolving merge conflicts.