]>
Commit | Line | Data |
---|---|---|
6a06907d XL |
1 | # Using Git |
2 | ||
3 | <!-- toc --> | |
4 | ||
5 | The Rust project uses [Git] to manage its source code. In order to | |
6 | contribute, you'll need some familiarity with its features so that your changes | |
7 | can be incorporated into the compiler. | |
8 | ||
9 | [Git]: https://git-scm.com | |
10 | ||
11 | The goal of this page is to cover some of the more common questions and | |
12 | problems new contributors face. Although some Git basics will be covered here, | |
13 | if you find that this is still a little too fast for you, it might make sense | |
14 | to first read some introductions to Git, such as the Beginner and Getting | |
15 | started sections of [this tutorial from Atlassian][atlassian-git]. GitHub also | |
16 | provides [documentation] and [guides] for beginners, or you can consult the | |
17 | more in depth [book from Git]. | |
18 | ||
19 | [book from Git]: https://git-scm.com/book/en/v2/ | |
20 | [atlassian-git]: https://www.atlassian.com/git/tutorials/what-is-version-control | |
923072b8 | 21 | [documentation]: https://docs.github.com/en/get-started/quickstart/set-up-git |
6a06907d XL |
22 | [guides]: https://guides.github.com/introduction/git-handbook/ |
23 | ||
24 | ## Prerequisites | |
25 | ||
26 | We'll assume that you've installed Git, forked [rust-lang/rust], and cloned the | |
27 | forked repo to your PC. We'll use the command line interface to interact | |
28 | with Git; there are also a number of GUIs and IDE integrations that can | |
29 | generally do the same things. | |
30 | ||
31 | [rust-lang/rust]: https://github.com/rust-lang/rust | |
32 | ||
33 | If you've cloned your fork, then you will be able to reference it with `origin` | |
34 | in your local repo. It may be helpful to also set up a remote for the official | |
35 | rust-lang/rust repo via | |
36 | ||
37 | ```sh | |
38 | git remote add upstream https://github.com/rust-lang/rust.git | |
39 | ``` | |
40 | ||
41 | if you're using HTTPS, or | |
42 | ||
43 | ```sh | |
44 | git remote add upstream git@github.com:rust-lang/rust.git | |
45 | ``` | |
46 | ||
47 | if you're using SSH. | |
48 | ||
136023e0 XL |
49 | **NOTE:** This page is dedicated to workflows for `rust-lang/rust`, but will likely be |
50 | useful when contributing to other repositories in the Rust project. | |
51 | ||
52 | ||
6a06907d XL |
53 | ## Standard Process |
54 | ||
55 | Below is the normal procedure that you're likely to use for most minor changes | |
56 | and PRs: | |
57 | ||
58 | 1. Ensure that you're making your changes on top of master: | |
59 | `git checkout master`. | |
136023e0 XL |
60 | 2. Get the latest changes from the Rust repo: `git pull upstream master --ff-only`. |
61 | (see [No-Merge Policy](#keeping-things-up-to-date) for more info about this). | |
6a06907d XL |
62 | 3. Make a new branch for your change: `git checkout -b issue-12345-fix`. |
63 | 4. Make some changes to the repo and test them. | |
64 | 5. Stage your changes via `git add src/changed/file.rs src/another/change.rs` | |
65 | and then commit them with `git commit`. Of course, making intermediate commits | |
66 | may be a good idea as well. Avoid `git add .`, as it makes it too easy to | |
67 | unintentionally commit changes that should not be committed, such as submodule | |
68 | updates. You can use `git status` to check if there are any files you forgot | |
69 | to stage. | |
136023e0 XL |
70 | 6. Push your changes to your fork: `git push --set-upstream origin issue-12345-fix` |
71 | (After adding commits, you can use `git push` and after rebasing or | |
72 | pulling-and-rebasing, you can use `git push --force-with-lease`). | |
73 | 7. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s master branch. | |
6a06907d XL |
74 | |
75 | [ghpullrequest]: https://guides.github.com/activities/forking/#making-a-pull-request | |
76 | ||
136023e0 XL |
77 | If you end up needing to rebase and are hitting conflicts, see [Rebasing](#rebasing). |
78 | If you want to track upstream while working on long-running feature/issue, see | |
79 | [Keeping things up to date](#keeping-things-up-to-date). | |
80 | ||
6a06907d XL |
81 | If your reviewer requests changes, the procedure for those changes looks much |
82 | the same, with some steps skipped: | |
83 | ||
84 | 1. Ensure that you're making changes to the most recent version of your code: | |
85 | `git checkout issue-12345-fix`. | |
86 | 2. Make, stage, and commit your additional changes just like before. | |
87 | 3. Push those changes to your fork: `git push`. | |
88 | ||
89 | ## Troubleshooting git issues | |
90 | ||
91 | You don't need to clone `rust-lang/rust` from scratch if it's out of date! | |
92 | Even if you think you've messed it up beyond repair, there are ways to fix | |
93 | the git state that don't require downloading the whole repository again. | |
94 | Here are some common issues you might run into: | |
95 | ||
96 | ### I deleted my fork on GitHub! | |
97 | ||
98 | This is not a problem from git's perspective. If you run `git remote -v`, | |
99 | it will say something like this: | |
100 | ||
101 | ``` | |
102 | $ git remote -v | |
103 | origin https://github.com//rust-lang/rust (fetch) | |
104 | origin https://github.com//rust-lang/rust (push) | |
105 | personal https://github.com/jyn514/rust (fetch) | |
106 | personal https://github.com/jyn514/rust (push) | |
107 | ``` | |
108 | ||
109 | If you renamed your fork, you can change the URL like this: | |
110 | ||
111 | ```console | |
112 | git remote set-url personal <URL> | |
113 | ``` | |
114 | ||
115 | where the `<URL>` is your new fork. | |
116 | ||
117 | ### I see 'Untracked Files: src/stdarch'? | |
118 | ||
119 | This is left over from the move to the `library/` directory. | |
120 | Unfortunately, `git rebase` does not follow renames for submodules, so you | |
121 | have to delete the directory yourself: | |
122 | ||
123 | ```console | |
124 | rm -r src/stdarch | |
125 | ``` | |
126 | ||
127 | ### I see `<<< HEAD`? | |
128 | ||
129 | You were probably in the middle of a rebase or merge conflict. See | |
130 | [Conflicts](#conflicts) for how to fix the conflict. If you don't care about the changes | |
131 | and just want to get a clean copy of the repository back, you can use `git reset`: | |
132 | ||
133 | ```console | |
134 | # WARNING: this throws out any local changes you've made! Consider resolving the conflicts instead. | |
135 | git reset --hard master | |
136 | ``` | |
137 | ||
138 | ### Quick note about submodules | |
139 | ||
140 | When updating your local repository with `git pull`, you may notice that sometimes | |
141 | Git says you have modified some files that you have never edited. For example, | |
142 | running `git status` gives you something like (note the `new commits` mention): | |
143 | ||
144 | ``` | |
145 | On branch master | |
146 | Your branch is up to date with 'origin/master'. | |
147 | ||
148 | Changes not staged for commit: | |
149 | (use "git add <file>..." to update what will be committed) | |
150 | (use "git restore <file>..." to discard changes in working directory) | |
151 | modified: src/tools/cargo (new commits) | |
152 | modified: src/tools/rls (new commits) | |
6a06907d XL |
153 | |
154 | no changes added to commit (use "git add" and/or "git commit -a") | |
155 | ``` | |
156 | ||
157 | These changes are not changes to files: they are changes to submodules (more on | |
158 | this [later](#git-submodules)). To get rid of those, run `git submodule update` | |
159 | (or run any `x.py` command, which will automatically update the submodules). | |
5099ac24 FG |
160 | Note that there is (as of <!-- date: 2022-02 --> February 2022) a [bug][#77620] if you use |
161 | worktrees, submodules, and `x.py` in a commit hook. If you run into an error | |
6a06907d XL |
162 | like: |
163 | ||
164 | ``` | |
165 | error: failed to read `/home/joshua/rustc-worktree/src/tools/miri/cargo-miri/Cargo.toml` | |
166 | ||
167 | Caused by: | |
168 | No such file or directory (os error 2) | |
169 | ``` | |
136023e0 | 170 | it's not anything you did wrong. There is a workaround in [the issue][#77620-workaround]. |
6a06907d | 171 | |
136023e0 XL |
172 | [#77620]: https://github.com/rust-lang/rust/issues/77620 |
173 | [#77620-workaround]: https://github.com/rust-lang/rust/issues/77620#issuecomment-705228229 | |
6a06907d | 174 | |
136023e0 | 175 | ## Rebasing and Conflicts |
6a06907d XL |
176 | |
177 | When you edit your code locally, you are making changes to the version of | |
178 | rust-lang/rust that existed when you created your feature branch. As such, when | |
179 | you submit your PR it is possible that some of the changes that have been made | |
180 | to rust-lang/rust since then are in conflict with the changes you've made. | |
181 | ||
182 | When this happens, you need to resolve the conflicts before your changes can be | |
183 | merged. First, get a local copy of the conflicting changes: Checkout your local | |
184 | master branch with `git checkout master`, then `git pull upstream master` to | |
185 | update it with the most recent changes. | |
186 | ||
187 | ### Rebasing | |
188 | ||
189 | You're now ready to start the rebasing process. Checkout the branch with your | |
190 | changes and execute `git rebase master`. | |
191 | ||
192 | When you rebase a branch on master, all the changes on your branch are | |
193 | reapplied to the most recent version of master. In other words, Git tries to | |
194 | pretend that the changes you made to the old version of master were instead | |
195 | made to the new version of master. During this process, you should expect to | |
196 | encounter at least one "rebase conflict." This happens when Git's attempt to | |
197 | reapply the changes fails because your changes conflicted with other changes | |
198 | that have been made. You can tell that this happened because you'll see | |
199 | lines in the output that look like | |
200 | ||
201 | ``` | |
202 | CONFLICT (content): Merge conflict in file.rs | |
203 | ``` | |
204 | ||
205 | When you open these files, you'll see sections of the form | |
206 | ||
207 | ``` | |
208 | <<<<<<< HEAD | |
209 | Original code | |
210 | ======= | |
211 | Your code | |
212 | >>>>>>> 8fbf656... Commit fixes 12345 | |
213 | ``` | |
214 | ||
215 | This represents the lines in the file that Git could not figure out how to | |
216 | rebase. The section between `<<<<<<< HEAD` and `=======` has the code from | |
217 | master, while the other side has your version of the code. You'll need to | |
218 | decide how to deal with the conflict. You may want to keep your changes, | |
219 | keep the changes on master, or combine the two. | |
220 | ||
221 | Generally, resolving the conflict consists of two steps: First, fix the | |
222 | particular conflict. Edit the file to make the changes you want and remove the | |
223 | `<<<<<<<`, `=======` and `>>>>>>>` lines in the process. Second, check the | |
224 | surrounding code. If there was a conflict, its likely there are some logical | |
225 | errors lying around too! It's a good idea to run `x.py check` here to make sure | |
226 | there are no glaring errors. | |
227 | ||
228 | Once you're all done fixing the conflicts, you need to stage the files that had | |
229 | conflicts in them via `git add`. Afterwards, run `git rebase --continue` to let | |
230 | Git know that you've resolved the conflicts and it should finish the rebase. | |
cdc7bbd5 | 231 | |
6a06907d XL |
232 | Once the rebase has succeeded, you'll want to update the associated branch on |
233 | your fork with `git push --force-with-lease`. | |
234 | ||
235 | Note that `git push` will not work properly and say something like this: | |
236 | ||
237 | ``` | |
238 | ! [rejected] issue-xxxxx -> issue-xxxxx (non-fast-forward) | |
239 | error: failed to push some refs to 'https://github.com/username/rust.git' | |
240 | hint: Updates were rejected because the tip of your current branch is behind | |
241 | hint: its remote counterpart. Integrate the remote changes (e.g. | |
242 | hint: 'git pull ...') before pushing again. | |
243 | hint: See the 'Note about fast-forwards' in 'git push --help' for details. | |
244 | ``` | |
245 | ||
246 | The advice this gives is incorrect! Because of Rust's | |
247 | ["no-merge" policy](#no-merge-policy) the merge commit created by `git pull` | |
248 | will not be allowed in the final PR, in addition to defeating the point of the | |
249 | rebase! Use `git push --force-with-lease` instead. | |
250 | ||
136023e0 XL |
251 | ### Keeping things up to date |
252 | ||
253 | The above section on [Rebasing](#rebasing) is a specific | |
254 | guide on rebasing work and dealing with merge conflicts. | |
255 | Here is some general advice about how to keep your local repo | |
256 | up-to-date with upstream changes: | |
257 | ||
258 | Using `git pull upstream master` while on your local master branch regularly | |
259 | will keep it up-to-date. You will also want to rebase your feature branches | |
260 | up-to-date as well. After pulling, you can checkout the feature branches | |
261 | and rebase them: | |
262 | ||
263 | ``` | |
264 | git checkout master | |
265 | git pull upstream master --ff-only # to make certain there are no merge commits | |
266 | git checkout feature_branch | |
267 | git rebase master | |
268 | git push --force-with-lease (set origin to be the same as local) | |
269 | ``` | |
270 | ||
94222f64 | 271 | To avoid merges as per the [No-Merge Policy](#no-merge-policy), you may want to use |
c295e0f8 XL |
272 | `git config pull.ff only` (this will apply the config only to the local repo) |
273 | to ensure that Git doesn't create merge commits when `git pull`ing, without | |
274 | needing to pass `--ff-only` or `--rebase` every time. | |
136023e0 XL |
275 | |
276 | You can also `git push --force-with-lease` from master to keep your origin's master in sync with | |
277 | upstream. | |
278 | ||
6a06907d XL |
279 | ## Advanced Rebasing |
280 | ||
281 | If your branch contains multiple consecutive rewrites of the same code, or if | |
282 | the rebase conflicts are extremely severe, you can use | |
283 | `git rebase --interactive master` to gain more control over the process. This | |
284 | allows you to choose to skip commits, edit the commits that you do not skip, | |
285 | change the order in which they are applied, or "squash" them into each other. | |
286 | ||
287 | Alternatively, you can sacrifice the commit history like this: | |
288 | ||
289 | ``` | |
290 | # squash all the changes into one commit so you only have to worry about conflicts once | |
291 | git rebase -i $(git merge-base master HEAD) # and squash all changes along the way | |
292 | git rebase master | |
293 | # fix all merge conflicts | |
294 | git rebase --continue | |
295 | ``` | |
296 | ||
297 | "Squashing" commits into each other causes them to be merged into a single | |
298 | commit. Both the upside and downside of this is that it simplifies the history. | |
299 | On the one hand, you lose track of the steps in which changes were made, but | |
300 | the history becomes easier to work with. | |
301 | ||
302 | You also may want to squash just the last few commits together, possibly | |
303 | because they only represent "fixups" and not real changes. For example, | |
304 | `git rebase --interactive HEAD~2` will allow you to edit the two commits only. | |
305 | ||
cdc7bbd5 XL |
306 | ### `git range-diff` |
307 | ||
308 | After completing a rebase, and before pushing up your changes, you may want to | |
309 | review the changes between your old branch and your new one. You can do that | |
310 | with `git range-diff master @{upstream} HEAD`. | |
311 | ||
312 | The first argument to `range-diff`, `master` in this case, is the base revision | |
313 | that you're comparing your old and new branch against. The second argument is | |
314 | the old version of your branch; in this case, `@upstream` means the version that | |
315 | you've pushed to GitHub, which is the same as what people will see in your pull | |
316 | request. Finally, the third argument to `range-diff` is the *new* version of | |
317 | your branch; in this case, it is `HEAD`, which is the commit that is currently | |
318 | checked-out in your local repo. | |
319 | ||
320 | Note that you can also use the equivalent, abbreviated form `git range-diff | |
321 | master @{u} HEAD`. | |
322 | ||
323 | Unlike in regular Git diffs, you'll see a `-` or `+` next to another `-` or `+` | |
324 | in the range-diff output. The marker on the left indicates a change between the | |
325 | old branch and the new branch, and the marker on the right indicates a change | |
326 | you've committed. So, you can think of a range-diff as a "diff of diffs" since | |
327 | it shows you the differences between your old diff and your new diff. | |
328 | ||
329 | Here's an example of `git range-diff` output (taken from [Git's | |
330 | docs][range-diff-example-docs]): | |
331 | ||
332 | ``` | |
333 | -: ------- > 1: 0ddba11 Prepare for the inevitable! | |
334 | 1: c0debee = 2: cab005e Add a helpful message at the start | |
335 | 2: f00dbal ! 3: decafe1 Describe a bug | |
336 | @@ -1,3 +1,3 @@ | |
337 | Author: A U Thor <author@example.com> | |
338 | ||
339 | -TODO: Describe a bug | |
340 | +Describe a bug | |
341 | @@ -324,5 +324,6 | |
342 | This is expected. | |
343 | ||
344 | -+What is unexpected is that it will also crash. | |
345 | ++Unexpectedly, it also crashes. This is a bug, and the jury is | |
346 | ++still out there how to fix it best. See ticket #314 for details. | |
347 | ||
348 | Contact | |
349 | 3: bedead < -: ------- TO-UNDO | |
350 | ``` | |
351 | ||
352 | (Note that `git range-diff` output in your terminal will probably be easier to | |
353 | read than in this example because it will have colors.) | |
354 | ||
355 | Another feature of `git range-diff` is that, unlike `git diff`, it will also | |
356 | diff commit messages. This feature can be useful when amending several commit | |
357 | messages so you can make sure you changed the right parts. | |
358 | ||
359 | `git range-diff` is a very useful command, but note that it can take some time | |
360 | to get used to its output format. You may also find Git's documentation on the | |
361 | command useful, especially their ["Examples" section][range-diff-example-docs]. | |
362 | ||
363 | [range-diff-example-docs]: https://git-scm.com/docs/git-range-diff#_examples | |
364 | ||
6a06907d XL |
365 | ## No-Merge Policy |
366 | ||
367 | The rust-lang/rust repo uses what is known as a "rebase workflow." This means | |
368 | that merge commits in PRs are not accepted. As a result, if you are running | |
369 | `git merge` locally, chances are good that you should be rebasing instead. Of | |
370 | course, this is not always true; if your merge will just be a fast-forward, | |
371 | like the merges that `git pull` usually performs, then no merge commit is | |
372 | created and you have nothing to worry about. Running `git config merge.ff only` | |
136023e0 | 373 | (this will apply the config to the local repo). |
6a06907d XL |
374 | once will ensure that all the merges you perform are of this type, so that you |
375 | cannot make a mistake. | |
376 | ||
377 | There are a number of reasons for this decision and like all others, it is a | |
378 | tradeoff. The main advantage is the generally linear commit history. This | |
379 | greatly simplifies bisecting and makes the history and commit log much easier | |
380 | to follow and understand. | |
381 | ||
382 | ## Git submodules | |
383 | ||
384 | **NOTE**: submodules are a nice thing to know about, but it *isn't* an absolute | |
385 | prerequisite to contribute to `rustc`. If you are using Git for the first time, | |
386 | you might want to get used to the main concepts of Git before reading this section. | |
387 | ||
388 | The `rust-lang/rust` repository uses [Git submodules] as a way to use other | |
389 | Rust projects from within the `rust` repo. Examples include Rust's fork of | |
17df50a5 | 390 | `llvm-project` and many devtools such as `cargo`, `rust-analyzer` and `rls`. |
6a06907d | 391 | |
17df50a5 | 392 | Those projects are developed and maintained in an separate Git (and GitHub) |
6a06907d XL |
393 | repository, and they have their own Git history/commits, issue tracker and PRs. |
394 | Submodules allow us to create some sort of embedded sub-repository inside the | |
395 | `rust` repository and use them like they were directories in the `rust` repository. | |
396 | ||
397 | Take `miri` for example. `miri` is maintained in the [`rust-lang/miri`] repository, | |
398 | but it is used in `rust-lang/rust` by the compiler for const evaluation. We bring it | |
399 | in `rust` as a submodule, in the `src/tools/miri` folder. | |
400 | ||
401 | The contents of submodules are ignored by Git: submodules are in some sense isolated | |
402 | from the rest of the repository. However, if you try to `cd src/tools/miri` and then | |
403 | run `git status`: | |
404 | ||
405 | ``` | |
406 | HEAD detached at 3fafb835 | |
407 | nothing to commit, working tree clean | |
408 | ``` | |
409 | ||
410 | As far as git is concerned, you are no longer in the `rust` repo, but in the `miri` repo. | |
3c0e092e | 411 | You will notice that we are in "detached HEAD" state, i.e. not on a branch but on a |
6a06907d XL |
412 | particular commit. |
413 | ||
414 | This is because, like any dependency, we want to be able to control which version to use. | |
415 | Submodules allow us to do just that: every submodule is "pinned" to a certain | |
416 | commit, which doesn't change unless modified manually. If you use `git checkout <commit>` | |
417 | in the `miri` directory and go back to the `rust` directory, you can stage this | |
5099ac24 FG |
418 | change like any other, e.g. by running `git add src/tools/miri`. (Note that if |
419 | you *don't* stage the change to commit, then you run the risk that running | |
420 | `x.py` will just undo your change by switching back to the previous commit when | |
421 | it automatically "updates" the submodules.) | |
422 | ||
423 | This version selection is usually done by the maintainers of the project, and | |
424 | looks like [this][miri-update]. | |
6a06907d XL |
425 | |
426 | Git submodules take some time to get used to, so don't worry if it isn't perfectly | |
427 | clear yet. You will rarely have to use them directly and, again, you don't need | |
428 | to know everything about submodules to contribute to Rust. Just know that they | |
429 | exist and that they correspond to some sort of embedded subrepository dependency | |
430 | that Git can nicely and fairly conveniently handle for us. | |
431 | ||
432 | [Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules | |
433 | [`rust-toolstate`]: https://rust-lang-nursery.github.io/rust-toolstate/ | |
434 | [`rust-lang/miri`]: https://github.com/rust-lang/miri | |
435 | [miri-update]: https://github.com/rust-lang/rust/pull/77500/files |