Skip to content

Add a section on how to use git #850

Closed
@jyn514

Description

@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.

Activity

added
E-easyDifficulty: might be a good place for a beginner
on Sep 6, 2020
jyn514

jyn514 commented on Sep 6, 2020

@jyn514
MemberAuthor

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

workingjubilee commented on Sep 6, 2020

@workingjubilee
Member

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

jyn514 commented on Sep 6, 2020

@jyn514
MemberAuthor

'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

workingjubilee commented on Sep 6, 2020

@workingjubilee
Member

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

workingjubilee commented on Sep 6, 2020

@workingjubilee
Member

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

spastorino commented on Sep 7, 2020

@spastorino
Member

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

jyn514 commented on Sep 7, 2020

@jyn514
MemberAuthor

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

spastorino

spastorino commented on Sep 7, 2020

@spastorino
Member

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

jyn514 commented on Sep 9, 2020

@jyn514
MemberAuthor

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

guswynn

guswynn commented on Sep 10, 2020

@guswynn
Contributor

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

jyn514 commented on Sep 10, 2020

@jyn514
MemberAuthor

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

GuillaumeGomez

GuillaumeGomez commented on Sep 11, 2020

@GuillaumeGomez
Member

@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

camelid commented on Sep 11, 2020

@camelid
Member

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

19 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    E-mediumDifficulty: might require some prior knowledge or code reading

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @spastorino@GuillaumeGomez@guswynn@jyn514@camelid

        Issue actions

          Add a section on how to use git · Issue #850 · rust-lang/rustc-dev-guide