Skip to main content
Oxen Workspaces function like a ‘repo within a repo’ – you can add, remove, and restore files to and from a workspace without affecting the repository it’s based off of.

​
Workspace Structure

A repository’s workspaces are stored in the workspaces folder of the .oxen hidden dir. Each workspace has a workspace_id or workspace_name with which it can be identified, as well as the commit_id of the commit in the repository that the workspace points to. You can have multiple workspaces for the same commit_id so long as they each have a different workspace_id Workspaces are useful when you want to work with a repository without downloading all of the data for it locally. To interact with one, you don’t have to have the remote repository’s contents pulled locally – you only need a local repo that’s pointing to the remote 
oxen init
oxen config --set-remote origin https://hub.oxen.ai/ox/ImageNet-1k
oxen workspace create --name extra_images # Create a workspace on a repository without pulling its contents
oxen workspace add new_images/ --workspace-name extra_images
oxen workspace commit -m "Add new images to dataset" -n extra_images
They’re also useful for doing imports of large amounts of files to a server. When you use oxen workspace add, you’re not writing any data to your local machine – Oxen processes and uploads the files directly to the remote. This allows you to avoid copying the files to a local repository like you would if you use the add --> commit --> push workflow, speeding up the operation and saving space on your machine 
oxen init
oxen config --create-remote --host hub.oxen.ai --scheme https --name ox/ImageNet-1k --add_readme
oxen workspace create # Create a workspace to import the data. This will return a workspace ID
oxen workspace add images/ --workspace-id [WORKSPACE_ID]
oxen workspace commit -m "Import 1 million images" -w [WORKSPACE_ID]

​
Instantiating a Workspace

Create a workspace with a remote repository and a branch name. 
from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "add-images")
If no branch name is provided, the default branch is used 
from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo)
On the server, this will base the workspace on the latest commit of the branch. As such, you can only create workspaces using branches that exist on the remote. Optionally, you can provide a name for the workspace 
from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, name="my-workspace-name")
Named workspaces are persistent. When you commit a named workspace, its commit_id will be updated to the newly created commit. Use a named workspace if you want make multiple commits with the same workspace

​
List Workspaces

You can list the workspaces for a remote using oxen workspace list 
oxen workspace list -r my_remote # Defaults to `origin` if no remote is provided

​
Adding Files

Use oxen workspace add to stage files to the workspace. This uploads the files’ contents directly to the server 
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 staged files

If you want to remove files staged to a workspace, you can unstage them with oxen workspace 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()) # 'images.jpg' will no longer be listed

​
Removing files from the base repo

On the other hand, you can use workspaces to remove files from the repository they’re based on. Stage files for removal with oxen workspace rm 
oxen workspace rm image.jpg -w my-workspace-id

​
Commit Changes

When you’re finished staging changes, you can commit the workspace to merge them into the base repo. 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 using a workspace", "add_images")
If you don’t provide a branch, the commit will be made to a new branch on the remote 
from oxen import RemoteRepo
from oxen import Workspace

repo = RemoteRepo("ox/CatDogBBox")
workspace = Workspace(repo, "my_branch") 
workspace.commit("adding an image using a workspace") # No branch is provided, so this will create a new branch
🎉 You have now committed data to the remote repo! Note: If merge conflicts are found, the workspace commit will fail, and you’ll have to resolve them to continue