Skip to content

Commit 3f083a0

Browse files
committed
feat: Add section about partial clones with git clone --filter='blob:none'
1 parent ed3365e commit 3f083a0

File tree

1 file changed

+24
-4
lines changed

1 file changed

+24
-4
lines changed

src/building/how-to-build-and-run.md

+24-4
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,29 @@ git clone https://github.com/rust-lang/rust.git
2525
cd rust
2626
```
2727

28+
### Partial clone the repository
29+
30+
Due to the size of the repository, cloning on a slower internet connection can take a long time,
31+
and requires disk space to store the full history of every file and directory.
32+
Instead, it is possible to tell git to perform a _partial clone_, which will only fully retrieve
33+
the current file contents, but will automatically retrieve further file contents when you, e.g.,
34+
jump back in the history.
35+
All git commands will continue to work as usual, at the price of requiring an internet connection
36+
to visit not-yet-loaded points in history.
37+
38+
```bash
39+
git clone --filter='blob:none' https://github.com/rust-lang/rust.git
40+
cd rust
41+
```
42+
43+
> **NOTE**: [This link](https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/)
44+
> describes this type of checkout in more detail, and also compares it to other modes, such as
45+
> shallow cloning.
46+
2847
### Shallow clone the repository
2948

30-
Due to the size of the repository, cloning on a slower internet connection can take a long time.
31-
To sidestep this, you can use the `--depth N` option with the `git clone` command.
49+
An older alternative to partial clones is to use shallow clone the repository instead.
50+
To do so, you can use the `--depth N` option with the `git clone` command.
3251
This instructs `git` to perform a "shallow clone", cloning the repository but truncating it to
3352
the last `N` commits.
3453

@@ -43,8 +62,9 @@ cd rust
4362

4463
> **NOTE**: A shallow clone limits which `git` commands can be run.
4564
> If you intend to work on and contribute to the compiler, it is
46-
> generally recommended to fully clone the repository [as shown above](#get-the-source-code).
47-
>
65+
> generally recommended to fully clone the repository [as shown above](#get-the-source-code),
66+
> or to perform a [partial clone](#shallow-clone-the-repository) instead.
67+
>
4868
> For example, `git bisect` and `git blame` require access to the commit history,
4969
> so they don't work if the repository was cloned with `--depth 1`.
5070

0 commit comments

Comments
 (0)