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.

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

​

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

​

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.

​

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.

​

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.

🎉 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.