Skip to content

Commit

Permalink
feat: Add section about partial clones with `git clone --filter='blob…
Browse files Browse the repository at this point in the history
…:none'`
  • Loading branch information
futile authored and Noratrieb committed Sep 24, 2024
1 parent ec77cdd commit c612fc3
Showing 1 changed file with 24 additions and 4 deletions.
28 changes: 24 additions & 4 deletions src/building/how-to-build-and-run.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,29 @@ git clone https://github.com/rust-lang/rust.git
cd rust
```

### Partial clone the repository

Due to the size of the repository, cloning on a slower internet connection can take a long time,
and requires disk space to store the full history of every file and directory.
Instead, it is possible to tell git to perform a _partial clone_, which will only fully retrieve
the current file contents, but will automatically retrieve further file contents when you, e.g.,
jump back in the history.
All git commands will continue to work as usual, at the price of requiring an internet connection
to visit not-yet-loaded points in history.

```bash
git clone --filter='blob:none' https://github.com/rust-lang/rust.git
cd rust
```

> **NOTE**: [This link](https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/)
> describes this type of checkout in more detail, and also compares it to other modes, such as
> shallow cloning.
### Shallow clone the repository

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

Expand All @@ -43,8 +62,9 @@ cd rust

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

0 comments on commit c612fc3

Please sign in to comment.