Oxen makes it feel like your dataset is local, even when it is not downloaded to the machine you are on.

​
Read a Remote Repository

If a remote repository already exists, you simply have to pass in the namespace/name of the remote repository you want to instantiate.

from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")

This is a cheap operation that just sets up the pointer to the remote repository. It does not download any data.

​
Create a Remote Repository

If you do not already have a remote repository, you can create one directly from Pyhton. You may want to start with an empty remote repository and add your data later.

from oxen import RemoteRepo

repo = RemoteRepo.create("my-user/my-repo-name")

By default we add a README.md file to the repository with an initial commit. If you want to create an empty repository without adding a README.md you can pass empty=True to the create method.

from oxen import RemoteRepo

repo = RemoteRepo.create("my-user/my-repo-name", empty=True)

The reason you may want to start with an empty repository is if you already started a local repository and want to push it to the remote repository. This local repository already has a commit history. When pushing to a remote, commit histories must match. Hence we need to start with an empty remote repository without any commits if we want to push a local repository with a commit history.

​
File Exploration

To see the files in the remote repository you can use ls.

from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")
print(repo.ls())

To view a specific directory you can pass the directory name to the ls method.

Note: the directories are paginated so you will need to use the page_num parameter to view the next page of results. There are also total_pages, page_number, and total_entries attributes that give you information about the pagination.

from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")
images_results = repo.ls("images", page_num=1, page_size=10)
print(images_results)
print(images_results.total_pages)
print(images_results.page_number)
print(images_results.total_entries)

​
Downloading Data

You can download subsets of the data if you do not need the entire data repository for your job.

from oxen import RemoteRepo
repo = RemoteRepo("ox/CatDogBBox")
repo.download("images/000000002754.jpg")

​
Checkout a Branch

If you have a data on a separate branch that you want to view you can checkout a branch by passing the branch name to the checkout method.

Python
from oxen import RemoteRepo
repo = RemoteRepo("ox/CatDogBBox")
repo.checkout("my-branch-name")
print(repo.ls())

​
Create a New Branch

The checkout method also allows you to create a new branch if the branch does not exist.

Python
from oxen import RemoteRepo
repo = RemoteRepo("ox/CatDogBBox")
repo.checkout("my-new-branch-name", create=True)
print(repo.ls())

​
View Branches

To see all the branches in the remote repository you can use the branches method.

Python
from oxen import RemoteRepo
repo = RemoteRepo("ox/CatDogBBox")
print(repo.branches())

​
Point Local to Remote

Remote repositories are identified by a remote URL. This is the URL that you can use to clone the repository.

Python
from oxen import RemoteRepo

repo = RemoteRepo.create("my-user/my-repo-name", empty=True)
print(repo.url())

You can use this URL to clone the repository.

Python
# Local Repository
from oxen import Repo
from oxen import RemoteRepo

remote_repo = RemoteRepo.create("my-user/my-repo-name", empty=True)
repo_url = remote_repo.url()

local_repo = Repo("/path/to/local/repo")
local_repo.clone(repo_url)

Or you can set the remote of a local repository to the remote repository.

Python
from oxen import Repo
from oxen import RemoteRepo

remote_repo = RemoteRepo.create("my-user/my-repo-name", empty=True)
repo_url = remote_repo.url()

local_repo = Repo("/path/to/local/repo")
remote_repo.set_remote("origin", remote_repo.url())