@@ -188,7 +188,70 @@ with one another are rolled up.
188
188
Speaking of tests, Rust has a comprehensive test suite. More information about
189
189
it can be found [ here] [ rctd ] .
190
190
191
- ### External Dependencies
191
+ ### External Dependencies (subtree)
192
+
193
+ As a developer to this repository, you don't have to treat the following external projects
194
+ differently from other crates that are directly in this repo:
195
+
196
+ * none so far, see https://github.com/rust-lang/rust/issues/70651 for more info
197
+
198
+ They are just regular files and directories. This is in contrast to ` submodule ` dependencies
199
+ (see below for those). Only tool authors will actually use any operations here.
200
+
201
+ #### Synchronizing a subtree
202
+
203
+ There are two synchronization directions: ` subtree push ` and ` subtree pull ` .
204
+
205
+ ```
206
+ git subtree push -P src/tools/clippy git@github.com:your-github-name/rust-clippy sync-from-rust
207
+ ```
208
+
209
+ takes all the changes that
210
+ happened to the copy in this repo and creates commits on the remote repo that match the local
211
+ changes. Every local commit that touched the subtree causes a commit on the remote repo, but is
212
+ modified to move the files from the specified directory to the tool repo root.
213
+
214
+ Make sure to not pick the ` master ` branch on the tool repo, so you can open a normal PR to the tool
215
+ to merge that subrepo push.
216
+
217
+ ```
218
+ git subtree pull -P src/tools/clippy https://github.com/rust-lang/rust-clippy master
219
+ ```
220
+
221
+ takes all changes since the last ` subtree pull ` from the tool repo
222
+ repo and adds these commits to the rustc repo + a merge commit that moves the tool changes into
223
+ the specified directory in the rust repository.
224
+
225
+ It is recommended that you always do a push first and get that merged to the tool master branch.
226
+ Then, when you do a pull, the merge works without conflicts.
227
+ While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict
228
+ resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to
229
+ rebase the result of a ` git subtree pull ` , rebasing merge commits is a bad idea in general.
230
+
231
+ You always need to specify the ` -P ` prefix to the subtree directory and the corresponding remote
232
+ repository. If you specify the wrong directory or repository
233
+ you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
234
+ Luckily you can just abort this without any consequences by throwing away either the pulled commits
235
+ in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
236
+ that this is happening because you suddenly get thousands of commits that want to be synchronized.
237
+
238
+ #### Creating a new subtree dependency
239
+
240
+ If you want to create a new subtree dependency from an existing repository, call (from this
241
+ repository's root directory!)
242
+
243
+ ```
244
+ git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
245
+ ```
246
+
247
+ This will create a new commit, which you may not rebase under any circumstances! Delete the commit
248
+ and redo the operation if you need to rebase.
249
+
250
+ Now you're done, the ` src/tools/clippy ` directory behaves as if clippy were part of the rustc
251
+ monorepo, so no one but you (or others that synchronize subtrees) actually needs to use ` git subtree ` .
252
+
253
+
254
+ ### External Dependencies (submodules)
192
255
193
256
Currently building Rust will also build the following external projects:
194
257
@@ -221,7 +284,6 @@ before the PR is merged.
221
284
222
285
Rust's build system builds a number of tools that make use of the
223
286
internals of the compiler. This includes
224
- [ Clippy] ( https://github.com/rust-lang/rust-clippy ) ,
225
287
[ RLS] ( https://github.com/rust-lang/rls ) and
226
288
[ rustfmt] ( https://github.com/rust-lang/rustfmt ) . If these tools
227
289
break because of your changes, you may run into a sort of "chicken and egg"
0 commit comments