Skip to main content
The day-to-day Oxen workflow follows the same shape as git: stage what’s changed, commit it, and inspect the history when you need to.

​
Stage Files

Add files to a repository with oxen add. This copies the files’ contents to the repository’s version store and stages the changes for commit. You can use absolute paths or paths relative to the repo root.
You can also stage matching files with glob patterns and wildcards. This stages everything that matches the pattern and isn’t excluded by .oxenignore.
oxen add handles new, modified, and removed files and directories. Oxen lets you version any data type — text, images, audio, video, parquet, etc. — in the same repository, and you interact with all of them through the same commands. Under the hood, Oxen stores type-specific file metadata to power richer features.

​
View Status

To see what is tracked, staged, modified, removed, or not yet added, use oxen status.
Output:
Because Oxen is built for large datasets with many files, status rolls up directory-level changes and summarizes them. You can paginate through staged files with the -s (skip) and -l (limit) flags. Run oxen status --help for the full list.

​
Commit Changes

Once changes are staged, commit them with a message.
This creates a new commit on the current branch. If the repository was previously empty, this also creates the main branch. After a commit, a copy of each file’s contents lives in the repository’s version store (by default .oxen/versions/files). File and directory metadata are stored in the Merkle Tree, which mirrors the working directory structure.

​
View History

Show the commit history of your current branch with oxen log.
Output:

​
View Diffs

Oxen can compute and display diffs between files using the oxen diff command.
This compares dataset.csv in the working directory with its version in the HEAD commit. You can also diff different files against each other, files across revisions, or whole revisions against each other. See the diff concepts page for the full set of options.

​
View File Contents

To print the raw bytes of a file as they exist at a revision, use oxen cat. The contents are written to stdout, so you can pipe them into another tool or redirect them to a file without restoring the file into your working directory.
Output:
By default oxen cat reads from HEAD. Pass --revision (or -r) to read the file as it existed at a specific branch or commit.
oxen cat streams the exact stored bytes, so it works on any file type, including binary data. Pipe the output into another tool rather than printing binary straight to your terminal, which can garble it.
To get a file’s metadata (hash, size, data type) instead of its contents — pairing with oxen cat — use oxen info. Pass --revision (or -r) to describe the file as it existed at a specific branch or commit, and --json for machine-readable output. Without --revision, oxen info describes the file in your working tree.
Output:

​
Restore Files

To revert changes you’ve made to a file in the working directory, use oxen restore. This restores the file to its version in the HEAD commit, and works on both modified and deleted files.
You can also restore directories — oxen restore will recursively restore the files inside. To restore from a specific commit or branch, pass --source.
Like git, you can also unstage files (without changing the working directory) using --staged.

​
Remove Files

To stage a file to be removed from the next commit, use oxen rm.
The file must already be committed for this to work. If you want to remove a file that has not been committed yet, just use your shell’s rm command. To recursively remove a directory, use the -r flag.
You can also remove entries from the staging area only — without deleting the file from the working directory — using --staged.