Repository navigation
Add a section on how to use git #850
Description
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.
Activity
jyn514 commentedon Sep 6, 2020
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 commentedon Sep 6, 2020
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 commentedon Sep 6, 2020
'Git tips' would also be a useful section (maybe near
git worktreein 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 ofgit add .? That would help prevent committing submodules in the first place.workingjubilee commentedon Sep 6, 2020
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 commentedon Sep 6, 2020
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 commentedon Sep 7, 2020
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 commentedon Sep 7, 2020
Hmm, that's mostly just branching - I'd like to cover rebasing in more depth. It's a good start though :)
spastorino commentedon Sep 7, 2020
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 commentedon Sep 9, 2020
Another good section would be how to squash commits (related to #824, but with less setup preferably).
guswynn commentedon Sep 10, 2020
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 commentedon Sep 10, 2020
In the meantime, @GuillaumeGomez has a great blog post about this here: https://blog.guillaume-gomez.fr/Git-tips/1/1
GuillaumeGomez commentedon Sep 11, 2020
@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 commentedon Sep 11, 2020
Yeah, VS Code has decent interactive support for resolving merge conflicts.
camelid commentedon Sep 11, 2020
I would say instructions on resolving merge conflicts might be the most needed; they still scare me :)
jyn514 commentedon Sep 13, 2020
This could also mention
git range-difffor reviewers: rust-lang/rust#76571 (comment)camelid commentedon Sep 13, 2020
Wow, I've wanted something like that!
JakobDegen commentedon Sep 22, 2020
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 commentedon Sep 24, 2020
Related: rust-lang/triagebot#821
jyn514 commentedon Sep 30, 2020
The remaining things to cover after #890:
git range-diffgit rebase -i master,git rebase -i $(git merge-base HEAD master)git pushfforgit push --force-with-leasegit add -p,git checkout -p,git checkout <commit-ish>? I use these a lot but they're not required, just helpful.LeSeulArtichaut commentedon Oct 3, 2020
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-leaseisgpf. It often reduces git commands to just 3, or rarely 4 lettersLeSeulArtichaut commentedon Oct 3, 2020
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.
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.
I like these a lot too, but I don't think they deserve a lot of attention. Basically saying "oh
git add -plets you stage your changes interactively would be enough.Definitely required here. Subodules were the most confusing thing that existed in the
rustrepository. 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 commentedon Oct 3, 2020
Right, I was imagining a separate 'git for reviewers' section, maybe even on a separate page so they're easy to distinguish.
Yeah ... I still have a ton of trouble with submodules. There are long term plans to move to
git subtreebut I think it's blocked on upstream bugs: rust-lang/rust#70651LeSeulArtichaut commentedon Oct 7, 2020
Started writing about submodules
jyn514 commentedon Mar 26, 2023
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.