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

# Workspace

<a id="oxen.workspace" />

# oxen.workspace

<a id="oxen.workspace.Workspace" />

## Workspace Objects

```python theme={null}
class Workspace()
```

The Workspace class allows you to interact with an Oxen workspace
without downloading the data locally.

Workspaces can be created off a branch and is tied to the commit id of the branch
at the time of creation.

You can commit a Workspace back to the same branch if the branch has not
advanced, otherwise you will have to commit to a new branch and merge.

## Examples

### Adding Files to a Workspace

Create a workspace from a branch.

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

# Connect to the remote repo
repo = RemoteRepo("ox/CatDogBBox")

# Create the workspace
workspace = Workspace(repo, "my-branch")

# Add a file to the workspace
workspace.add("my-image.png")

# Print the status of the workspace
status = workspace.status()
print(status.added_files())

# Commit the workspace
workspace.commit("Adding my image to the workspace.")
```

<a id="oxen.workspace.Workspace.__init__" />

## \_\_init\_\_

```python theme={null}
def __init__(repo: "RemoteRepo",
             branch: str,
             workspace_id: Optional[str] = None,
             workspace_name: Optional[str] = None,
             path: Optional[str] = None)
```

Create a new Workspace.

**Arguments**:

* `repo` - `PyRemoteRepo`
  The remote repo to create the workspace from.
* `branch` - `str`
  The branch name to create the workspace from. The workspace
  will be tied to the commit id of the branch at the time of creation.
* `workspace_id` - `Optional[str]`
  The workspace id to create the workspace from.
  If left empty, will create a unique workspace id.
* `workspace_name` - `Optional[str]`
  The name of the workspace. If left empty, the workspace will have no name.
* `path` - `Optional[str]`
  The path to the workspace. If left empty, the workspace will be created in the root of the remote repo.

<a id="oxen.workspace.Workspace.id" />

## id

```python theme={null}
@property
def id()
```

Get the id of the workspace.

<a id="oxen.workspace.Workspace.name" />

## name

```python theme={null}
@property
def name()
```

Get the name of the workspace.

<a id="oxen.workspace.Workspace.branch" />

## branch

```python theme={null}
@property
def branch()
```

Get the branch that the workspace is tied to.

<a id="oxen.workspace.Workspace.commit_id" />

## commit\_id

```python theme={null}
@property
def commit_id()
```

Get the commit id of the workspace.

<a id="oxen.workspace.Workspace.repo" />

## repo

```python theme={null}
@property
def repo() -> "RemoteRepo"
```

Get the remote repo that the workspace is tied to.

<a id="oxen.workspace.Workspace.status" />

## status

```python theme={null}
def status(path: str = "")
```

Get the status of the workspace.

**Arguments**:

* `path` - `str`
  The path to check the status of.

<a id="oxen.workspace.Workspace.add" />

## add

```python theme={null}
def add(src: str, dst: str = "")
```

Add a file to the workspace

**Arguments**:

* `src` - `str`
  The path to the local file to be staged
* `dst` - `str`
  The path in the remote repo where the file will be added

<a id="oxen.workspace.Workspace.rm" />

## rm

```python theme={null}
def rm(path: str)
```

Remove a file from the workspace

**Arguments**:

* `path` - `str`
  The path to the file on workspace to be removed

<a id="oxen.workspace.Workspace.commit" />

## commit

```python theme={null}
def commit(message: str, branch_name: Optional[str] = None) -> PyCommit
```

Commit the workspace to a branch

**Arguments**:

* `message` - `str`
  The message to commit with
* `branch_name` - `Optional[str]`
  The name of the branch to commit to. If left empty, will commit to the branch
  the workspace was created from.

<a id="oxen.workspace.Workspace.delete" />

## delete

```python theme={null}
def delete()
```

Delete the workspace