# Coming from Git

Oak will feel familiar — repos, branches, push, pull, diff — but a few of Git's defaults are deliberately turned around. This page is the translation table.

## What's different, in short

- **No staging area.** `oak commit` snapshots the whole working tree (or just the paths you name). There's no `add`.
- **No commit messages.** Commits are checkpoints. The *branch* carries the message, set with `oak desc`, and it becomes the message of the squash commit on `main`.
- **No local `main`.** `main` lives on the server. Locally you're always on a feature branch; `oak switch main` is an error, not a checkout.
- **One kind of merge.** Merging a branch onto `main` always squashes it to a single commit. There's no merge-commit or rebase option to choose between, and no pull-request object — the branch *is* the review unit.
- **Pull merges, never rebases.** `oak pull` merges the latest `main` into your branch. History on your branch is never rewritten under you.
- **Clones are optional.** `oak mount` gives you a working tree backed by the server, with files fetched on first read.
- **Large files are normal files.** Content is chunked and deduplicated (FastCDC + BLAKE3), so there's no LFS to set up.

## Command mapping

| Git | Oak | Notes |
|---|---|---|
| `git init` | `oak init` | Also offers to import an existing `.git` history. |
| `git clone <url>` | `oak clone <org>/<repo>` | A Git URL works too — it's imported. |
| `git clone --depth 1` | `oak clone --shallow` | |
| `git sparse-checkout` | `oak clone --path <dir>`, `oak sparse` | See [Sparse clones](/docs/sparse-clones). |
| `git worktree add` | `oak mount <org>/<repo> <dir>` | No clone behind each one. See [Lazy mounts](/docs/mounts). |
| `git status` | `oak status` | `--short`/`--porcelain` are Git-compatible. |
| `git diff` | `oak diff` | Opens a full-screen viewer on a terminal; `--print` for plain output. |
| `git diff main...feature` | `oak diff feature` | Shows what the branch contributes. |
| `git add -A && git commit -m …` | `oak commit` | `-m` is refused. Describe the branch with `oak desc`. |
| `git commit --amend -m …` | `oak desc "…"` | Change what the branch says it does. |
| `git push` | `oak push` | Publishes the current branch. Pushes to `main` are refused. |
| `git pull` / `git pull --rebase` | `oak pull` | Always merges `main` into your branch. |
| `git fetch` | `oak fetch` | Refreshes your copy of `main`. |
| `git switch <b>` / `git checkout <b>` | `oak switch <b>` | Fetches the branch if you don't have it. |
| `git switch -c <b>` | `oak switch -c [<b>]` | Name is optional; one is generated. |
| `git checkout <sha>` | `oak checkout <sha>` / `oak switch -d <sha>` | Detached HEAD. |
| `git branch` | `oak branch` / `oak branch list` | `--remote` reads the server. |
| `git branch --show-current` | `oak branch --show-current` | |
| `git branch -d <b>` | `oak close <b>` | Closed branches can be reopened from the web. |
| `git merge` / "Squash and merge" | `oak merge` | Server-side squash onto `main`. |
| `git rebase -i` | `oak split` | Reorder, drop, or split a branch's commits into separate branches. |
| `git restore <path>` | `oak restore <path>` | `-s <commit>` to restore from elsewhere. |
| `git reset --hard` | `oak reset` | Discards uncommitted changes. |
| `git log` | `oak log` | `-S` / `-G` pickaxe search work as in Git. |
| `git rev-parse HEAD` | `oak hash` / `oak rev-parse HEAD` | |
| `git archive` | `oak archive` | Zip of the working tree. |
| `.gitignore` | `.oakignore` | Same syntax. Oak falls back to `.gitignore` when there's no `.oakignore`. |
| `.git/hooks/pre-commit` | `.oak/hooks/pre-commit` | Local only, like Git. |
| GitHub Actions | `.oak/workflows/*.yml` | [Native CI](/docs/ci), GitHub-Actions-shaped but much smaller. |
| `CODEOWNERS` | `.oak/PERMISSIONS` | Controls *read access*, not review. See [Path permissions](/docs/path-permissions). |

## Things Git has that Oak doesn't (yet)

Being honest about the gaps:

- **Tags.** There's no tag object; refer to commits by hash.
- **Issues, pull-request review threads, line comments.** Review happens on the branch page and in the CLI (`oak branch review`), not in comment threads.
- **Submodules.** Imports skip them.
- **Push to arbitrary remotes.** You push to an Oak server. To leave, `oak export` writes a complete Git repo you can push anywhere.
- **Branch rename.** `oak branch rename` is temporarily disabled.

## Using Git tools against an Oak repo

Stock `git` can clone any public Oak repo as a **read-only snapshot of `main`**:

```bash
git clone https://oak.space/acme/web.git
```

That's one commit with no history, meant for tooling (package managers, `/plugin marketplace add`, deploy scripts). For full history in Git form, use `oak export`. Both are covered in [Git import, export, and interop](/docs/git).

> **Inside an Oak checkout, don't run `git`.** An Oak repo has a `.oak/` directory and no `.git`. If a tool insists on Git, export or snapshot-clone into a separate directory instead.