Skip to content

Explain how to work with subtree #70654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 14, 2020
Merged

Explain how to work with subtree #70654

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
04c8191
Explain how to work with subrepos
oli-obk Apr 1, 2020
56d0c81
s/subrepo/subtree/
oli-obk Apr 1, 2020
521eb0d
Git subtree is upstream, no need to install
oli-obk Apr 1, 2020
af55352
Explain that you have to specify path and repository during subrepo s…
oli-obk Apr 1, 2020
59cfb80
Triple backticks
oli-obk Apr 1, 2020
df91b40
Address review comments
oli-obk Apr 2, 2020
7928c45
Address reviews
oli-obk Apr 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 43 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,49 @@ with one another are rolled up.
Speaking of tests, Rust has a comprehensive test suite. More information about
it can be found [here][rctd].

### External Dependencies
### External Dependencies (subtree)

As a developer to this repository, you don't have to treat the following external projects
differently from other crates that are directly in this repo:

* none so far, see https://github.com/rust-lang/rust/issues/70651 for more info

They are just regular files and directories. This is in contrast to `submodule` dependencies
(see below for those).

#### Synchronizing a subtree

There are two synchronization directions: `subtree push` and `subtree pull`.

A `git subtree push -P src/tools/clippy`
takes all the changes that
happened to the copy in this repo and creates commits on the remote repo that match the local
changes (so every local commit that touched the subtree causes a commit on the remote repo).

A `git subtree pull -P src/tools/clippy` takes all changes since the last `subtree pull` from the clippy
repo and creates a single commit in the rustc repo with all the changes.

You always need to specifiy the `-P` prefix to the subtree directory. If you specify the wrong directory
you'll get very fun merges that try to push the wrong directory to the remote repository. Luckily you
can just abort this without any consequences.

#### Creating a new subtree dependency

If you want to create a new subtree dependency from an existing repository, call (from this
repository's root directory!!)

```
git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
```

This will create a new commit, which you may not rebase under any circumstances! Delete the commit
and redo the operation if you need to rebase.

Now you're done, the `src/tools/clippy` directory behaves as if clippy were part of the rustc
monorepo, so no one but you (or others that synchronize subtrees) needs actually use `git subtree`.


### External Dependencies (submodules)

Currently building Rust will also build the following external projects:

Expand Down Expand Up @@ -221,7 +263,6 @@ before the PR is merged.

Rust's build system builds a number of tools that make use of the
internals of the compiler. This includes
[Clippy](https://github.com/rust-lang/rust-clippy),
[RLS](https://github.com/rust-lang/rls) and
[rustfmt](https://github.com/rust-lang/rustfmt). If these tools
break because of your changes, you may run into a sort of "chicken and egg"
Expand Down