<!-- # hard line break macro for HTML -->

# fiftyone.utils.github

GitHub utilities.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

| [`GitHubRepository`](#fiftyone.utils.github.GitHubRepository)(repo[, safe])   | Class for interacting with a GitHub repository.   |
|-------------------------------------------------------------------------------|---------------------------------------------------|

### *class* fiftyone.utils.github.GitHubRepository(repo, safe=False)

Bases: `object`

Class for interacting with a GitHub repository.

#### NOTE
To interact with private GitHub repositories that you have access to,
provide your GitHub personal access token by setting the
`GITHUB_TOKEN` environment variable.

* **Parameters:**
  * **repo** – 

    the GitHub repository or identifier, which can be:
    - a GitHub repo URL like `https://github.com/<user>/<repo>`
    - a GitHub ref like
      `https://github.com/<user>/<repo>/tree/<branch>` or
      `https://github.com/<user>/<repo>/commit/<commit>`
    - a GitHub ref string like `<user>/<repo>[/<ref>]`
  * **safe** (*False*) – whether to allow `repo` to contain a tree path like
    `https://github.com/<user>/<repo>/tree/<branch>/<path>`. If
    `safe=True` and a `<path>` is found, it is extracted and stored
    in the [`safe_path()`](#fiftyone.utils.github.GitHubRepository.safe_path) property

**Attributes:**

| [`user`](#fiftyone.utils.github.GitHubRepository.user)             | The username of the repo.                                  |
|--------------------------------------------------------------------|------------------------------------------------------------|
| [`repo`](#fiftyone.utils.github.GitHubRepository.repo)             | The name of the repo.                                      |
| [`ref`](#fiftyone.utils.github.GitHubRepository.ref)               | The ref (e.g. branch, tag, commit hash), if any.           |
| [`safe_path`](#fiftyone.utils.github.GitHubRepository.safe_path)   | The path that was extracted from the provided ref, if any. |
| [`identifier`](#fiftyone.utils.github.GitHubRepository.identifier) | The repository identifier string.                          |

**Methods:**

| [`get_repo_info`](#fiftyone.utils.github.GitHubRepository.get_repo_info)()                      | Returns a dict of info about the repository.               |
|-------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| [`get_file`](#fiftyone.utils.github.GitHubRepository.get_file)(path[, outpath])                 | Downloads the file at the given path.                      |
| [`list_path_contents`](#fiftyone.utils.github.GitHubRepository.list_path_contents)([path])      | Returns the contents of the repo rooted at the given path. |
| [`list_repo_contents`](#fiftyone.utils.github.GitHubRepository.list_repo_contents)([recursive]) | Returns a flat list of the repository's contents.          |
| [`download`](#fiftyone.utils.github.GitHubRepository.download)(outdir)                          | Downloads the repository to the specified root directory.  |
| [`parse_url`](#fiftyone.utils.github.GitHubRepository.parse_url)(url)                           |                                                            |
| [`parse_identifier`](#fiftyone.utils.github.GitHubRepository.parse_identifier)(identifier)      |                                                            |

#### *property* user

The username of the repo.

#### *property* repo

The name of the repo.

#### *property* ref

The ref (e.g. branch, tag, commit hash), if any.

#### *property* safe_path

The path that was extracted from the provided ref, if any.

#### *property* identifier

The repository identifier string.

#### get_repo_info()

Returns a dict of info about the repository.

* **Returns:**
  an info dict

#### get_file(path, outpath=None)

Downloads the file at the given path.

* **Parameters:**
  * **path** – the filepath in the repository
  * **outpath** (*None*) – a path on disk to write the file
* **Returns:**
  the file bytes, if no `outpath` is provided

#### list_path_contents(path=None)

Returns the contents of the repo rooted at the given path.

#### NOTE
This method has a limit of 1,000 files.
[Documentation](https://docs.github.com/en/rest/repos/contents).

* **Parameters:**
  **path** (*None*) – an optional root path to start the search from
* **Returns:**
  a list of file info dicts

#### list_repo_contents(recursive=True)

Returns a flat list of the repository’s contents.

#### NOTE
This method has a limit of 100,000 entries and 7MB response size.
[Documentation](https://docs.github.com/en/rest/git/trees).

* **Parameters:**
  **recursive** (*True*) – whether to recursively traverse subdirectories
* **Returns:**
  a list of file info dicts

#### download(outdir)

Downloads the repository to the specified root directory.

* **Parameters:**
  **outdir** – the output directory

#### *static* parse_url(url)

#### *static* parse_identifier(identifier)