# Repositories

Create a repository, choose who can see it, clone and browse it, change its settings, and delete or restore it, from the web app, the CLI and the API.

## Create and push

```sh
sailfork repo create ocean-landing --about "Landing page for the ocean project"
git remote add origin https://git.sailfork.com/fenil/ocean-landing.git
git push -u origin main
```

The repository is private unless you pass `--public`. To create it under an organization you belong to, name it `acme/ocean-landing`. For the address to give git, how it signs in and what a push refuses, see [Git over HTTPS and SSH](https://status.sailfork.com/docs/git-access).

## Create a repository

### In the web app

Open `https://status.sailfork.com/new`. The form is called **Create a repository**.

1. Under **Owner**, pick your account or an organization you belong to.
2. Under **Name**, type the name. The address you will get shows under the field.
3. Optionally fill in **About**, up to 350 characters.
4. Under **Visibility**, choose **Public** or **Private**.
5. Choose **Create repository**.

The repository starts empty. The page shows the commands to push to it, or you can [move one over from GitHub](https://status.sailfork.com/docs/migrate). The form starts on **Public** for your own account and on the organization's default for an organization. Check it before you create.

### From the CLI

```sh
sailfork repo create ocean-landing --private --about "Landing page"
sailfork repo create acme/site --public
sailfork repo list --owner acme --visibility private
```

`repo create` takes `--about`, `--public` and `--private` (the default). `repo list` shows your repositories and your organizations'. It takes `--owner <handle>`, `--visibility public|private` and `--limit`.

### Names

A name is 1 to 100 letters, digits, `-`, `_` or `.`. It cannot be `.` or `..` and cannot end in `.git`. A few names are taken by owner pages and are refused: `activity`, `caissons`, `inbox`, `issues`, `llms.txt`, `migration`, `repositories` and `settings`. Names are compared without regard to case. A name that another repository left behind when it was moved or when its owner was renamed is also held, and the error says to choose another.

## Public and private

A public repository can be read and cloned by anyone, with no sign-in. A private one is visible only to people with access. Writing needs access either way, with one exception: someone without write access to a public repository can push branches named `contrib/<their handle>/...` and open pull requests from them. Those branches stay out of default clones and branch lists.

Change visibility in the web app under **Settings**, **General**, **Visibility**, or from the CLI:

```sh
sailfork repo edit -R fenil/ocean-landing --visibility public
```

Making a repository public asks you to type its name first. It makes all code on every branch and tag public, the full commit history including anything removed from the latest version, and its issues and pull requests. Forks that were made while it was public stay public when you make it private again.

## Open a repository

The repository page is at `https://status.sailfork.com/<owner>/<repo>`. The tabs are **Code**, **Commits**, **Pull requests**, **Issues**, **Branches**, **Releases**, **Runs**, **Mirrors** and **Settings**. Signed-out visitors do not see **Mirrors** or **Settings**.

### Code

- **Files.** Folders and files list the last commit that touched each one. A folder bar offers **Go to file**, **New file** (if you can write) and **History**.
- **README.** The folder's `README.md`, found case-insensitively, renders under the file list on the repository page and on each folder page.
- **A file.** Choose a file to read it. **Code** and **Blame** switch between the plain view and who last changed each line (`?view=blame`). Blame works on text files up to 1 MiB. A file over 10 MiB shows its size and a download, with the first 256 KB of a text file below it. Images and PDFs show as themselves. Markdown and MDX show as a preview, CSV and TSV as a table, Jupyter notebooks as their cells and SVG as a picture, each with **Code** beside it for the source. A file stored in Git LFS shows the real file, not the pointer. The file bar also has **History**, **Wrap lines**, **Copy**, **Raw** and **Download**. See [Code review](https://status.sailfork.com/docs/code-review#rendered-diffs-and-files) for how the same files read in a diff. People who can write also see **Edit** and **Delete**, and edits are committed as you. For a public repository you cannot write to, **Propose a change** starts a pull request instead.
- **Clone.** The **Clone** box shows an HTTPS command and, when the server offers SSH, an SSH one. For a repository of 256 MiB or more it adds `--filter=blob:none`, and from 1 GiB `--depth 1 --filter=blob:none`, and says so. Run `git fetch --unshallow` for the full history.

### Commits

**Commits** lists a branch newest first, grouped by day. Choose a commit to read its changes. A path filter shows the history of one file or folder. The compare page shows how one branch, tag or commit differs from another, and is where a new pull request starts.

### From the CLI

You can read a repository without a clone:

```sh
sailfork repo view -R fenil/ocean-landing
sailfork repo log --limit 10 --path src/tide
sailfork repo tree src --ref main
sailfork repo cat README.md --ref v1.2.0
sailfork repo find '**/*.md' --limit 20
sailfork repo compare main tide-fix --patch
sailfork repo refs load_config
```

`--ref` takes a branch, tag or commit and defaults to the default branch. `repo cat --raw` writes the bytes of a binary file. `repo refs <symbol>` lists where a symbol is defined and each line that uses it. Inside a clone, `-R owner/repo` is not needed.

To clone, use:

```sh
sailfork repo clone fenil/ocean-landing
sailfork repo clone fenil/ocean-landing --protocol ssh
sailfork repo clone acme/site site-copy -- --depth 1
```

It runs `git clone` with sign-in already wired. A plain full clone goes through a faster path that installs the stored packs, and the clone's `origin` stays an `https://` address. `--protocol ssh` falls back to HTTPS, and says so, when the SSH port cannot be reached from your network. Anything after `--` goes to git.

## Settings

Open **Settings** on the repository. **General** holds what is saved today:

| Setting | Notes |
| --- | --- |
| **Description** | Shown under the name and in search. |
| **Visibility** | Public or private, as above. |
| **Default branch** | Where pull requests land and what clones check out. It must be a branch that exists. |

The screen also has **Cloning**, **Merging**, **Branch rules**, **Owners**, **Merge queue**, **Tags**, **Secrets**, **Webhooks** and **Transfer or delete**. See [Clone defaults](#clone-defaults) below, [Branches and protection](https://status.sailfork.com/docs/branches) for merge rules, branch rules, the merge queue and tags, and [CI](https://status.sailfork.com/docs/ci) for secrets.

From the CLI:

```sh
sailfork repo edit -R acme/site --about "The marketing site"
sailfork repo edit -R acme/site --visibility public
sailfork repo edit -R acme/site --default-branch trunk
```

Send one field per call. Only repository admins can change these. An organization repository's change is written to the organization's audit log.

### Clone defaults

A large repository can say how `sailfork repo clone` clones it when the person cloning passes no options. Repository admins set it under **Settings**, **Cloning**:

| Setting | What a plain `repo clone` does |
| --- | --- |
| **Blobless** | Makes a blobless partial clone (`--filter=blob:none`): the history and folders arrive at once, and a file's contents arrive when it is checked out. |
| **Folders to check out** | Makes a sparse checkout of these folders, plus the files at the root. Leave it empty for the whole tree. Naming folders also makes the clone blobless. |

The screen shows the command and what it will do. With neither set, the clone is the whole repository with every file. Set the same from the CLI, then clear it:

```sh
sailfork repo edit -R acme/site --clone-sparse web --clone-sparse docs --clone-blobless true
sailfork repo edit -R acme/site --clear-clone-defaults
```

`--clone-sparse` replaces the folder list, and a call that sets only one of the two keeps the other. A call changes one field, and the clone defaults count as one, so they cannot come with `--about`, `--visibility` or `--default-branch`. They are stored with `cloneDefaults` on `PATCH /api/repos/{owner}/{repo}`.

A clone takes the defaults only when it passes none of its own. These win over them:

- `--sparse <folder>` (repeat for more) checks out only those folders, blobless.
- `--full` clones the whole repository and ignores the defaults.
- `--filter` or `--sparse` after `--` goes to git as given, and the defaults are not applied.

A clone from a URL instead of `owner/repo` has no defaults to read.

### Default branch

A new repository's default branch is `main`. If the first branch you push is `master` and there is no `main`, the default switches to `master`. Change it any time in **Settings**, **General**, **Default branch**. Pull requests target it by default, clones check it out, and merge rules apply to it. You cannot delete it until you change it.

### Transfer

**Settings**, **Transfer or delete**, **Transfer** moves the repository to an organization you belong to or to your own account. Pull requests, issues and history come along. Clone URLs change to the new owner, so update your remotes.

## Delete and restore

```sh
sailfork repo delete -R acme/site --dry-run
sailfork repo delete -R acme/site --yes
sailfork repo restore -R acme/site
sailfork repo purge -R acme/site --yes
```

Deleting schedules removal 14 days out and hides the repository at once. Clones and pushes fail, and the repository answers 404, until you restore it. In the web app, choose **Delete repository** under **Settings**, **Transfer or delete**, and type the name. The page then shows the deletion date and **Cancel deletion**. After the 14 days an hourly job removes the git data and the record, and you cannot get it back. Only repository admins can delete or restore.

To remove a scheduled repository at once instead of waiting, purge it: `sailfork repo purge`, or **Purge now** next to **Cancel deletion**, and type the name. Its git data, issues, pull requests and files are deleted right away and cannot be restored. A repository under a legal hold cannot be purged.

## For scripts and agents

Every step above has a route: `POST /api/repos`, `PATCH /api/repos/{owner}/{repo}`, `DELETE /api/repos/{owner}/{repo}`, `DELETE /api/repos/{owner}/{repo}/deletion` and `POST /api/repos/{owner}/{repo}/transfer`. See [the REST API](https://status.sailfork.com/docs/api) for authentication and errors. `POST /api/repos` also takes a `readme` (up to 64 KiB), which becomes `README.md` in the first commit on `main`. Creating a repository needs a token with the `repo:admin` scope. Agents can read files, search and commit through [caissons](https://status.sailfork.com/docs/caissons) and the [MCP server](https://status.sailfork.com/docs/mcp) without a clone.

## Common errors

| Message | Cause and fix |
| --- | --- |
| `name must be 1 to 100 characters of letters, digits, '-', '_' or '.', and not end in .git` | Rename it. |
| `` `settings` is reserved for an owner page; choose another name `` | The name is on the reserved list above. |
| `a repository with this name already exists` | The owner already has one. Names are compared without case. |
| `the name ocean-landing is still held by a repository that moved away from this address; choose another` | Another repository was transferred or renamed away from that address. |
| `about must be at most 350 characters` | Shorten the description. |
| Exit code 4 from the CLI | The repository does not exist, or it is private and you cannot see it. |

---

Every docs page: https://status.sailfork.com/llms.txt
