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

# 📦 Workspaces

> Workspaces allow you to add and commit data to a repository without having to download it locally

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

<CodeGroup>
  ```bash CLI theme={null}
  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
  ```

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

  repo = RemoteRepo("ox/ImageNet-1k") # Host defaults to 'hub.oxen.ai'
  workspace = Workspace(repo, "extra-images")
  workspace.add("new_images/")

  status = workspace.status() # View the changes staged to the workspace
  print(status.added_files())

  workspace.commit("Add new images to dataset")
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash CLI theme={null}
  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]
  ```

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

  repo = RemoteRepo("ox/ImageNet-1k", files="README.md")
  workspace = Workspace(repo)
  workspace.add("images/")

  status = workspace.status()
  print(status.added_files())

  workspace.commit("Import 1 million images")
  ```
</CodeGroup>

## Instantiating a Workspace

Create a workspace with a remote repository and a branch name.

<CodeGroup>
  ```python Python theme={null}
  from oxen import RemoteRepo
  from oxen import Workspace

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

  ```bash CLI theme={null}
  oxen workspace create -w my-workspace-name -b add-images
  ```
</CodeGroup>

If no branch name is provided, the default branch is used

<CodeGroup>
  ```python Python theme={null}
  from oxen import RemoteRepo
  from oxen import Workspace

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

  ```bash CLI theme={null}
  oxen workspace create
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  from oxen import RemoteRepo
  from oxen import Workspace

  repo = RemoteRepo("ox/CatDogBBox")
  workspace = Workspace(repo, name="my-workspace-name")
  ```

  ```bash CLI theme={null}
  oxen workspace create -n my-workspace-name
  ```
</CodeGroup>

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`

<CodeGroup>
  ```bash CLI  theme={null}
  oxen workspace list -r my_remote # Defaults to `origin` if no remote is provided
  ```
</CodeGroup>

## Adding Files

Use `oxen workspace add` to stage files to the workspace. This uploads the files' contents directly to the server

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```bash CLI theme={null}
  oxen workspace add image.png -w my-workspace-id
  oxen workspace status -w my-workspace-id
  ```
</CodeGroup>

### Removing staged files

If you want to remove files staged to a workspace, you can unstage them with `oxen workspace rm --staged`.

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```bash CLI theme={null}
  oxen workspace rm --staged image.jpg -w my-workspace-id
  ```
</CodeGroup>

### 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`

<CodeGroup>
  ```bash CLI theme={null}
  oxen workspace rm image.jpg -w my-workspace-id
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```bash CLI theme={null}
  oxen workspace commit -m "adding an image" -w my-workspace-id -b add_images
  ```
</CodeGroup>

If you don't provide a branch, the commit will be made to a new branch on the remote

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```bash CLI theme={null}
  oxen workspace commit -m "adding an image" -w my-workspace-id # No branch is provided, so this will create a new branch
  ```

  If a workspace doesn't have a name, it will be deleted on commit. If it's named, it will be updated to point to the newly created commit
</CodeGroup>

🎉 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