Skip to content

[v1.0] Remove Repository class #3346

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 2 commits into from
Sep 12, 2025
Merged

[v1.0] Remove Repository class #3346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
550fb78
Remove Repository class + adapt docs
Wauplin Sep 11, 2025
46d6b90
remove fr git_vs_http
Wauplin Sep 11, 2025
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
17 changes: 2 additions & 15 deletions .github/workflows/python-tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,7 @@ jobs:
fail-fast: false
matrix:
python-version: ["3.9", "3.13"]
test_name:
[
"Repository only",
"Everything else",
"Inference only",
"Xet only"
]
test_name: ["Everything else", "Inference only", "Xet only"]
include:
- python-version: "3.13" # LFS not ran on 3.9
test_name: "lfs"
Expand Down Expand Up @@ -65,7 +59,7 @@ jobs:

case "${{ matrix.test_name }}" in

"Repository only" | "Everything else" | "Inference only")
"Everything else" | "Inference only")
sudo apt update
sudo apt install -y libsndfile1-dev
;;
Expand Down Expand Up @@ -112,13 +106,6 @@ jobs:

case "${{ matrix.test_name }}" in

"Repository only")
# Run repo tests concurrently
PYTEST="$PYTEST ../tests -k 'TestRepository' -n 4"
echo $PYTEST
eval $PYTEST
;;

"Inference only")
# Run inference tests concurrently
PYTEST="$PYTEST ../tests -k 'test_inference' -n 4"
Expand Down
5 changes: 1 addition & 4 deletions docs/source/cn/_toctree.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,4 @@
title: 概览
- local: guides/hf_file_system
title: Hugging Face 文件系统
- title: "concepts"
sections:
- local: concepts/git_vs_http
title: Git vs HTTP 范式

40 changes: 0 additions & 40 deletions docs/source/cn/concepts/git_vs_http.md
View file
Open in desktop

This file was deleted.

88 changes: 0 additions & 88 deletions docs/source/cn/guides/repository.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,91 +156,3 @@ GitRefs(
>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")
```

## 管理存储库的本地副本

上述所有操作都可以通过HTTP请求完成。然而，在某些情况下，您可能希望在本地拥有存储库的副本，并使用您熟悉的Git命令与之交互。

[`Repository`] 类允许您使用类似于Git命令的函数与Hub上的文件和存储库进行交互。它是对Git和Git-LFS方法的包装，以使用您已经了解和喜爱的Git命令。在开始之前，请确保已安装Git-LFS（请参阅[此处](https://git-lfs.github.com/)获取安装说明）。

### 使用本地存储库

使用本地存储库路径实例化一个 [`Repository`] 对象：

请运行以下代码：

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="<path>/<to>/<folder>")
```

### 克隆

`clone_from`参数将一个存储库从Hugging Face存储库ID克隆到由 `local_dir`参数指定的本地目录：

请运行以下代码：

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60")
```
`clone_from`还可以使用URL克隆存储库：

请运行以下代码：

```py
>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60")
```

你可以将`clone_from`参数与[`create_repo`]结合使用，以创建并克隆一个存储库：

请运行以下代码：

```py
>>> repo_url = create_repo(repo_id="repo_name")
>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url)
```

当你克隆一个存储库时，通过在克隆时指定`git_user`和`git_email`参数，你还可以为克隆的存储库配置Git用户名和电子邮件。当用户提交到该存储库时，Git将知道提交的作者是谁。

请运行以下代码：

```py
>>> repo = Repository(
... "my-dataset",
... clone_from="<user>/<dataset_id>",
... token=True,
... repo_type="dataset",
... git_user="MyName",
... git_email="me@cool.mail"
... )
```

### 分支

分支对于协作和实验而不影响当前文件和代码非常重要。使用[`~Repository.git_checkout`]来在不同的分支之间切换。例如，如果你想从 `branch1`切换到 `branch2`：

请运行以下代码：

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="huggingface-hub", clone_from="<user>/<dataset_id>", revision='branch1')
>>> repo.git_checkout("branch2")
```

### 拉取

[`~Repository.git_pull`] 允许你使用远程存储库的更改更新当前本地分支：

请运行以下代码：

```py
>>> from huggingface_hub import Repository
>>> repo.git_pull()
```

如果你希望本地的提交发生在你的分支被远程的新提交更新之后，请设置`rebase=True`：

```py
>>> repo.git_pull(rebase=True)
```
4 changes: 0 additions & 4 deletions docs/source/de/_toctree.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,3 @@
title: Integrieren einer Bibliothek
- local: guides/webhooks_server
title: Webhooks server
- title: "Konzeptionelle Anleitungen"
sections:
- local: concepts/git_vs_http
title: Git vs. HTTP-Paradigma
69 changes: 0 additions & 69 deletions docs/source/de/concepts/git_vs_http.md
View file
Open in desktop

This file was deleted.

2 changes: 0 additions & 2 deletions docs/source/en/_toctree.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,6 @@
title: Authentication
- local: package_reference/environment_variables
title: Environment variables
- local: package_reference/repository
title: Managing local and online repositories
- local: package_reference/hf_api
title: Hugging Face Hub API
- local: package_reference/file_download
Expand Down
82 changes: 0 additions & 82 deletions docs/source/en/guides/repository.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,85 +178,3 @@ that you should be aware of. For example, you can't transfer your repo to anothe
>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")
```

## Manage a local copy of your repository

All the actions described above can be done using HTTP requests. However, in some cases you might be interested in having
a local copy of your repository and interact with it using the Git commands you are familiar with.

The [`Repository`] class allows you to interact with files and repositories on the Hub with functions similar to Git commands. It is a wrapper over Git and Git-LFS methods to use the Git commands you already know and love. Before starting, please make sure you have Git-LFS installed (see [here](https://git-lfs.github.com/) for installation instructions).

<Tip warning={true}>

[`Repository`] is deprecated in favor of the http-based alternatives implemented in [`HfApi`]. Given its large adoption in legacy code, the complete removal of [`Repository`] will only happen in release `v1.0`. For more details, please read [this explanation page](./concepts/git_vs_http).

</Tip>

### Use a local repository

Instantiate a [`Repository`] object with a path to a local repository:

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="<path>/<to>/<folder>")
```

### Clone

The `clone_from` parameter clones a repository from a Hugging Face repository ID to a local directory specified by the `local_dir` argument:

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60")
```

`clone_from` can also clone a repository using a URL:

```py
>>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60")
```

You can combine the `clone_from` parameter with [`create_repo`] to create and clone a repository:

```py
>>> repo_url = create_repo(repo_id="repo_name")
>>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url)
```

You can also configure a Git username and email to a cloned repository by specifying the `git_user` and `git_email` parameters when you clone a repository. When users commit to that repository, Git will be aware of the commit author.

```py
>>> repo = Repository(
... "my-dataset",
... clone_from="<user>/<dataset_id>",
... token=True,
... repo_type="dataset",
... git_user="MyName",
... git_email="me@cool.mail"
... )
```

### Branch

Branches are important for collaboration and experimentation without impacting your current files and code. Switch between branches with [`~Repository.git_checkout`]. For example, if you want to switch from `branch1` to `branch2`:

```py
>>> from huggingface_hub import Repository
>>> repo = Repository(local_dir="huggingface-hub", clone_from="<user>/<dataset_id>", revision='branch1')
>>> repo.git_checkout("branch2")
```

### Pull

[`~Repository.git_pull`] allows you to update a current local branch with changes from a remote repository:

```py
>>> from huggingface_hub import Repository
>>> repo.git_pull()
```

Set `rebase=True` if you want your local commits to occur after your branch is updated with the new commits from the remote:

```py
>>> repo.git_pull(rebase=True)
```
Loading
Loading