An Oxen Workspace is a convenient construct for adding data. Conceptually you can think of a workspace a special type of branch where you can stage remote changes before committing them. Under the hood, a workspace is tied to a commit id. This means whatever changes you make will always be with respect to the commit you created the workspace off of.

​

Instantiating a Workspace

A workspace is created off of a RemoteRepo and a branch name. The branch name is just a convenience for the user to create a workspace on the underlying commit id.

from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "add-images")

If no branch name is provided, the workspace will be created off of the default branch (usually main).

from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo)

​

Adding Files

When adding data, it is always a good idea to create a branch for the changes you are about to make. This will allow you to commit changes without affecting the default branch.

​

Creating a Branch

from oxen import RemoteRepo

repo = RemoteRepo("ox/CatDogBBox")
# Create the branch on the remote
repo.create_branch("add-images")
# Make sure you are pointing to this branch
repo.checkout("add-images")

​

Uploading Files

Workspaces allow you to upload files without immediately committing them. Think of this as a staging area where you can upload the data, and then batch commit when you are ready.

from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "add-images")
workspace.add("/path/to/image.png")
status = workspace.status()
print(status.added_files())

​

Removing Uploaded Files

If you accidentally add file from the remote workspace and want to remove it, no worries, you can unstage it with oxen remote rm --staged.

from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "add-images")
workspace.rm("image.jpg")
status = workspace.status()
print(status.added_files())

​

Commit Changes

When you are confident in the changes you have made, you can commit the changes to the remote workspace. This will create a new commit on the remote branch.

from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "add-images")
workspace.commit("adding an image", "add-images")

🎉 You have now committed data to the remote branch without cloning the full repo.

Note: If the remote branch cannot be merged cleanly, the remote commit will fail, and you will have to resolve the merge conflicts with some more advanced commands which we will cover later.