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.

[camelid]

I would say instructions on resolving merge conflicts might be the most needed; they still scare me :)

[jyn514]

This could also mention git range-diff for reviewers: rust-lang/rust#76571 (comment)

[camelid]

Wow, I've wanted something like that!

[JakobDegen]

I'm going to start work on this. I'm not sure how it will go yet, but I'll do what I can and open a draft PR as soon as it makes sense so I can get feedback as soon as possible.

[jyn514]

Related: rust-lang/triagebot#821

[jyn514]

The remaining things to cover after #890:

• git range-diff
• git rebase -i master, git rebase -i $(git merge-base HEAD master)
• Possibly instructions for doing this in a GUI? We'd need some way to pick a specific gui, maybe it would be better to point to existing links on the internet.
• git aliases; @camelid suggested git pushf for git push --force-with-lease
• Maybe git add -p, git checkout -p, git checkout <commit-ish>? I use these a lot but they're not required, just helpful.
• Talk about submodules

[LeSeulArtichaut]

git aliases; @camelid suggested git pushf for git push --force-with-lease

I personally use ohmyzsh's git plugin, which basically has all the aliases I need, and much more. (Actually it has too many aliases, it's ridiculous.) For example, git push --force-with-lease is gpf. It often reduces git commands to just 3, or rarely 4 letters

[LeSeulArtichaut]

git range-diff

This one is mostly useful for reviewers, I don't think it should be a priority in the guide, I'm even unsure it should be there at all. It is definitely useful, but I think we shouldn't "spam" readers with a lot of commands they won't need, so they can focus on the ones that actually matter. Only my opinion though.

Possibly instructions for doing this in a GUI? We'd need some way to pick a specific gui, maybe it would be better to point to existing links on the internet.

I don't think we should pick a GUI and do a "tutorial" for that GUI. I think what we should do is maybe list a few popular GUIs that exist (GitKraken, SourceTree...?) or just throw this list that exists on git-scm.com. GUIs are designed to be intuitive so I don't think we should have to add more than that.

Maybe git add -p, git checkout -p, git checkout <commit-ish>? I use these a lot but they're not required, just helpful.

I like these a lot too, but I don't think they deserve a lot of attention. Basically saying "oh git add -p lets you stage your changes interactively would be enough.

Talk about submodules

Definitely required here. Subodules were the most confusing thing that existed in the rust repository. I had those weird one-line files that git showed as modified but I didn't modify, and guess what, those files don't even exist!

[jyn514]

This one is mostly useful for reviewers

Right, I was imagining a separate 'git for reviewers' section, maybe even on a separate page so they're easy to distinguish.

Talk about submodules

Definitely required here. Subodules were the most confusing thing that existed in the rust repository.

Yeah ... I still have a ton of trouble with submodules. There are long term plans to move to git subtree but I think it's blocked on upstream bugs: rust-lang/rust#70651

[LeSeulArtichaut]

Started writing about submodules

[jyn514]

I think at this point git.html is complete enough we can close this tracking issue and open individual issues for anything that's missing.