> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oxen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote repo

<a id="oxen.remote_repo" />

# oxen.remote\_repo

<a id="oxen.remote_repo.get_repo" />

## get\_repo

```python theme={null}
def get_repo(name: str, host: str = "hub.oxen.ai", scheme: str = "https")
```

Get a RemoteRepo object for the specified name. For example 'ox/CatDogBBox'.

**Arguments**:

* `name` - `str`
  Name of the repository in the format 'namespace/repo\_name'.
* `host` - `str`
  The host to connect to. Defaults to 'hub.oxen.ai'

**Returns**:

[RemoteRepo](/python-api/remote_repo)

<a id="oxen.remote_repo.create_repo" />

## create\_repo

```python theme={null}
def create_repo(name: str,
                description="",
                is_public: bool = True,
                host: str = "hub.oxen.ai",
                scheme: str = "https",
                files: List[Tuple[str, str]] = [])
```

Create a new repository on the remote server.

**Arguments**:

* `name` - `str`
  Name of the repository in the format 'namespace/repo\_name'.
* `description` - `str`
  Description of the repository.
  Only applicable to [OxenHub](https://oxen.ai).
* `is_public` - `bool`
  Whether the repository is public or private.
  Only applicable to [OxenHub](https://oxen.ai).
* `host` - `str`
  The host to connect to. Defaults to 'hub.oxen.ai'
* `scheme` - `str`
  The scheme to use for the remote url. Default: 'https'
* `files` - `List[Tuple[str, str]]`
  A list of tuples containing the path to the file and the contents
  of the file that you would like to seed the repository with.

**Returns**:

[RemoteRepo](/python-api/remote_repo)

<a id="oxen.remote_repo.RemoteRepo" />

## RemoteRepo Objects

```python theme={null}
class RemoteRepo()
```

The RemoteRepo class allows you to interact with an Oxen repository
without downloading the data locally.

## Examples

### Add & Commit Files

Adding and committing a file to a remote workspace.

```python theme={null}
from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")
repo.add("/path/to/image.png")
status = repo.status()
print(status.added_files())
repo.commit("Adding my image to the remote workspace.")
```

### Downloading Specific Files

Grab a specific file revision and load it into pandas.

```python theme={null}
from oxen import RemoteRepo
import pandas as pd

# Connect to the remote repo
repo = RemoteRepo("ox/CatDogBBox")
# Specify the version of the file you want to download
branch = repo.get_branch("my-pets")
# Download takes a file or directory a commit id
repo.download("annotations", revision=branch.commit_id)
# Once you have the data locally, use whatever library you want to explore the data
df = pd.read_csv("annotations/train.csv")
print(df.head())
```

<a id="oxen.remote_repo.RemoteRepo.__init__" />

## \_\_init\_\_

```python theme={null}
def __init__(repo_id: str,
             host: str = "hub.oxen.ai",
             revision: str = "main",
             scheme: str = "https")
```

Create a new RemoteRepo object to interact with.

**Arguments**:

* `repo_id` - `str`
  Name of the repository in the format 'namespace/repo\_name'.
  For example 'ox/chatbot'
* `host` - `str`
  The host to connect to. Defaults to 'hub.oxen.ai'
* `revision` - `str`
  The branch name or commit id to checkout. Defaults to 'main'
* `scheme` - `str`
  The scheme to use for the remote url. Default: 'https'

<a id="oxen.remote_repo.RemoteRepo.create" />

## create

```python theme={null}
def create(empty: bool = False, is_public: bool = False)
```

Will create the repo on the remote server.

**Arguments**:

* `empty` - `bool`
  Whether to create an empty repo or not. Default: False
* `is_public` - `bool`
  Whether the repository is public or private. Default: False

<a id="oxen.remote_repo.RemoteRepo.exists" />

## exists

```python theme={null}
def exists() -> bool
```

Checks if this remote repo exists on the server.

<a id="oxen.remote_repo.RemoteRepo.delete" />

## delete

```python theme={null}
def delete()
```

Delete this remote repo from the server.

<a id="oxen.remote_repo.RemoteRepo.checkout" />

## checkout

```python theme={null}
def checkout(revision: str, create=False)
```

Switches the remote repo to the specified revision.

**Arguments**:

* `revision` - `str`
  The name of the branch or commit id to checkout.
* `create` - `bool`
  Whether to create a new branch if it doesn't exist. Default: False

<a id="oxen.remote_repo.RemoteRepo.ls" />

## ls

```python theme={null}
def ls(directory: Optional[str] = None,
       page_num: int = 1,
       page_size: int = 100)
```

Lists the contents of a directory in the remote repo.

**Arguments**:

* `directory` - `str`
  The directory to list. If None, will list the root directory.
* `page_num` - `int`
  The page number to return. Default: 1
* `page_size` - `int`
  The number of items to return per page. Default: 100

<a id="oxen.remote_repo.RemoteRepo.scan" />

## scan

```python theme={null}
def scan(directory: Optional[str] = None, page_size: int = 100)
```

Generator over the contents of a directory in the remote repo

**Arguments**:

* `directory` - `str`
  The directory to list. If None, will list the root directory
* `page_size` - `int`
  The number of items to return per page. Default: 100

<a id="oxen.remote_repo.RemoteRepo.download" />

## download

```python theme={null}
def download(src: str,
             dst: Optional[str] = None,
             revision: Optional[str] = None)
```

Download a file or directory from the remote repo.

**Arguments**:

* `src` - `str`
  The path to the remote file
* `dst` - `str | None`
  The path to the local file. If None, will download to
  the same path as `src`
* `revision` - `str | None`
  The branch or commit id to download. Defaults to `self.revision`

<a id="oxen.remote_repo.RemoteRepo.add" />

## add

```python theme={null}
def add(src: str,
        dst: Optional[str] = "",
        branch: Optional[str] = None,
        workspace_name: Optional[str] = None)
```

Stage a file to a workspace in the remote repo.

**Arguments**:

* `src` - `str`
  The path to the local file to upload
* `dst` - `str | None`
  The directory to upload the file to. If None, will upload to the root directory.
* `branch` - `str | None`
  The branch to upload the file to. Defaults to `self.revision`

**Returns**:

[Workspace](/python-api/workspace)

<a id="oxen.remote_repo.RemoteRepo.status" />

## status

```python theme={null}
def status()
```

Get the status of the workspace.

<a id="oxen.remote_repo.RemoteRepo.commit" />

## commit

```python theme={null}
def commit(message: str)
```

Commit the workspace to the remote repo.

<a id="oxen.remote_repo.RemoteRepo.upload" />

## upload

```python theme={null}
def upload(src: str,
           commit_message: str,
           file_name: Optional[str] = None,
           dst_dir: Optional[str] = "",
           branch: Optional[str] = None)
```

Upload a file to the remote repo.

**Arguments**:

* `src` - `str`
  The path to the local file to upload
* `file_name` - `str | None`
  The name of the file to upload. If None, will use the name of the file in `src`
* `dst_dir` - `str | None`
  The directory to upload the file to. If None, will upload to the root directory.
* `branch` - `str | None`
  The branch to upload the file to. Defaults to `self.revision`

<a id="oxen.remote_repo.RemoteRepo.metadata" />

## metadata

```python theme={null}
def metadata(path: str)
```

Get the metadata for a file in the remote repo.

<a id="oxen.remote_repo.RemoteRepo.file_exists" />

## file\_exists

```python theme={null}
def file_exists(path: str, revision: str = None)
```

Check if a file exists in the remote repo.

**Arguments**:

* `path` - `str`
  The path to the file to check
* `revision` - `str`
  The revision to check against, defaults to `self.revision`

<a id="oxen.remote_repo.RemoteRepo.file_has_changes" />

## file\_has\_changes

```python theme={null}
def file_has_changes(local_path: str,
                     remote_path: str = None,
                     revision: str = None)
```

Check if a local file has changed compared to a remote revision

**Arguments**:

* `local_path` - `str`
  The local path to the file to check
* `remote_path` - `str`
  The remote path to the file to check, will default to `local_path` if not provided
* `revision` - `str`
  The revision to check against, defaults to `self.revision`

<a id="oxen.remote_repo.RemoteRepo.log" />

## log

```python theme={null}
def log()
```

Get the commit history for a remote repo

<a id="oxen.remote_repo.RemoteRepo.branch_exists" />

## branch\_exists

```python theme={null}
def branch_exists(name: str) -> bool
```

Check if a branch exists in the remote repo.

**Arguments**:

* `name` - `str`
  The name of the branch to check

<a id="oxen.remote_repo.RemoteRepo.branch" />

## branch

```python theme={null}
def branch()
```

Get the current branch for a remote repo

<a id="oxen.remote_repo.RemoteRepo.branches" />

## branches

```python theme={null}
def branches()
```

List all branches for a remote repo

<a id="oxen.remote_repo.RemoteRepo.list_workspaces" />

## list\_workspaces

```python theme={null}
def list_workspaces()
```

List all workspaces for a remote repo

<a id="oxen.remote_repo.RemoteRepo.get_branch" />

## get\_branch

```python theme={null}
def get_branch(branch: str)
```

Return a branch by name on this repo, if exists

**Arguments**:

* `branch` - `str`
  The name of the branch to return

<a id="oxen.remote_repo.RemoteRepo.create_branch" />

## create\_branch

```python theme={null}
def create_branch(branch: str)
```

Return a branch by name on this repo,
creating it from the currently checked out branch if it doesn't exist

**Arguments**:

* `branch` - `str`
  The name to assign to the created branch

<a id="oxen.remote_repo.RemoteRepo.create_checkout_branch" />

## create\_checkout\_branch

```python theme={null}
def create_checkout_branch(branch: str)
```

Create a new branch from the currently checked out branch,
and switch to it

**Arguments**:

* `branch` - `str`
  The name to assign to the created branch

<a id="oxen.remote_repo.RemoteRepo.merge" />

## merge

```python theme={null}
def merge(base_branch: str, head_branch: str)
```

Merge the head branch into the base branch on the remote repo.

**Arguments**:

* `base_branch` - `str`
  The base branch to merge into
* `head_branch` - `str`
  The head branch to merge

<a id="oxen.remote_repo.RemoteRepo.namespace" />

## namespace

```python theme={null}
@property
def namespace() -> str
```

The namespace for the repo.

<a id="oxen.remote_repo.RemoteRepo.name" />

## name

```python theme={null}
@property
def name() -> str
```

The name of the repo.

<a id="oxen.remote_repo.RemoteRepo.identifier" />

## identifier

```python theme={null}
@property
def identifier()
```

The namespace/name of the repo.

<a id="oxen.remote_repo.RemoteRepo.url" />

## url

```python theme={null}
@property
def url() -> str
```

The remote url for the repo.

<a id="oxen.remote_repo.RemoteRepo.revision" />

## revision

```python theme={null}
@property
def revision() -> str
```

The branch or commit id for the repo