> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git in ReasonOS

> Every project is a git repository — host it on ReasonOS or point at any existing remote, browse it with nothing running, and open any branch as a live workspace.

A ReasonOS project is exactly one git repository. You can **host the repository
on ReasonOS** — clone and push directly, no third-party git host anywhere — or
**point a project at any existing git remote** and keep pushing wherever you
push today.

Either way, ReasonOS keeps its own synced copy of the repository. That copy is
what makes a project readable with nothing running: files, branches, history,
and change requests all render **without a branch node** — a server is what you
start when you want to *change* something, not what you need to read a README.

<Card title="Branches are workspaces" icon="server">
  ReasonOS runs one server per active branch. A branch and a workspace are the
  same object seen two ways: push to it with git, or open it in the editor and
  it is already running. See [Collaboration](/editor/collaboration) for what
  happens when several people open the same branch.
</Card>

## Where a project's code lives

When you create a project, the **Start from** choice decides the repository's
origin:

| Start from            | Where the code lives                                                                                               | Pushes go to                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
| **Import a git repo** | Your existing remote stays the origin; ReasonOS syncs a copy for browsing and review                               | Your remote, exactly as before |
| **RBS workspace**     | Hosted on ReasonOS; the default branch is born with a first commit — `WORKSPACE.rbs`, a README, and a `.gitignore` | ReasonOS                       |
| **Empty repository**  | Hosted on ReasonOS, nothing in it — for pushing a repository you already have                                      | ReasonOS                       |

The project name becomes part of its URLs (including the clone URL), so what
you type is folded into a slug — the creation screen shows exactly what the
name will be before you confirm.

<Note>
  GitHub and GitLab appear in the "Where the code lives" picker but connecting
  them as first-class hosts is still in progress. In the meantime, **Import a git
  repo** works with any remote URL — including repositories on GitHub or GitLab —
  using your SSH key.
</Note>

## Browsing a repository

Every project has a **Code** section with three tabs — **Files**, **Branches**,
and **Change requests** — plus a **History** section. All of it reads
ReasonOS's synced copy, so it works with no server running:

* **Files** — a tree browser with the last commit touching each path, the
  branch picker, and breadcrumbs. Each directory renders its README below the
  listing; files get syntax highlighting and a **Blame** toggle. Your position
  lives in the URL, so any file on any branch has a link you can share.
* **Search** — fixed-string code search over the branch you're browsing, with
  matches opening straight into the file.
* **Download** — a `.tar.gz` archive of the branch you're viewing.
* **History** — commits grouped by day; selecting one shows the commit's full
  diff.

If ReasonOS's copy is still syncing or the last sync failed, the page says so —
with what it last fetched and a retry — instead of silently serving stale refs.

Projects are **private** by default. A project marked **Public** (Settings →
General) is readable by everyone in your organization's ReasonOS, and — when
the organization itself is public — by signed-out visitors too: code, branches,
history, and change requests. Settings, CI runs, and build targets always
require signing in.

## Branches and branch nodes

The **Branches** tab is more than a ref list. Each row shows the branch's
divergence from the default branch (`↑2 ↓17`), its last commit, and — because
every branch can have a server — what that server is doing right now:
`server running`, `starting`, or `not responding`. A branch created in
ReasonOS that nobody has pushed to yet is tagged `not pushed yet`.

<Steps>
  <Step title="Create a branch">
    **New branch** creates the ref on the origin immediately. The **"Start a
    server for this branch"** checkbox is optional and unchecked by default —
    most branches never need one, and you can start one later.
  </Step>

  <Step title="Open the workspace">
    **Open workspace** (from the Files bar, a branch row, or the Workspace
    rail item) connects the editor to that branch's node, starting one if none
    is running. Everyone who opens the same branch lands on the same node —
    see [Collaboration](/editor/collaboration).
  </Step>

  <Step title="Stop or delete">
    Every branch row with a running server has a stop button. Deleting a
    branch deletes it **on the origin** — for everyone — and the default
    branch can't be deleted at all. Settings → **Branch servers** lists every
    running server with who is currently on it, so you know whether stopping
    one interrupts a teammate.
  </Step>
</Steps>

## Cloning and pushing

### ReasonOS-hosted repositories

The Files tab shows the clone URL with an HTTPS/SSH switch:

```bash theme={null}
# HTTPS
git clone https://reasonos.example.com/git/my-service.git

# SSH (the authenticated path from your own machine)
git clone ssh://git@reasonos.example.com:2222/my-service.git
```

* **SSH** authenticates with the public keys you register under your profile's
  **SSH keys** settings — paste a public key once and every hosted repository
  your organization gives you access to works. Pushing requires being a member
  of the project's organization, and the private key never leaves your
  machine.
* **HTTPS** serves signed-in reads, and public projects in a public
  organization clone anonymously — no credential at all. From a terminal on
  your own machine, use SSH for anything private.
* **Inside a workspace** there is nothing to set up: a branch node's checkout
  arrives already authenticated with its own short-lived repository
  credential.
* **Git LFS works out of the box** on hosted repositories — the endpoint is
  derived from the clone URL, so `git lfs push`/`pull` need no `.lfsconfig`.

A push to a hosted repository is only acknowledged once ReasonOS has durably
recorded it — an acked push is never lost. Pushes also flow through [branch
rules](#branch-rules) and trigger [CI workflows](/ci/overview) that match the
ref.

An **empty hosted repository** shows a quick-setup page with the exact
commands to bring existing code over:

```bash theme={null}
git remote add reasonos ssh://git@reasonos.example.com:2222/my-service.git
git push -u reasonos main
```

For a hosted **RBS workspace** project you can skip git entirely: "Open the
workspace" seeds the first commit server-side and connects you to a running
branch node.

### Imported repositories

Nothing about your git life changes: push to your existing remote exactly as
before. ReasonOS's synced copy notices new branches and commits and the
project's pages follow; every screen has a refresh for when you don't want to
wait for the next sync. Branches you create or delete in ReasonOS are created
and deleted **on your origin**, so the two never drift.

## Branch rules

Settings → **Branch rules** holds the project's protection rulesets. A ruleset
names a *set* of branches by pattern — the default branch, all branches, or a
pattern like `release/*` — so new branches fall under protection automatically
rather than needing a row someone remembers to create.

Rules cover the refs themselves:

* Restrict who can **create**, **update**, or **delete** matching branches
* **Block force pushes**
* **Require linear history** (no merge commits arrive by push; merges must
  squash or rebase)
* **Require signed commits**

and the review flow:

* **Require a change request** — matching branches move only through a merged
  change request; direct pushes are refused
* **Required approvals**, **dismiss stale approvals**, **require approval from
  someone other than the last pusher**, **require review threads resolved**
* **Required checks** — named [CI workflows](/ci/overview) that must pass at
  the exact revision being merged
* **Allowed merge methods**

Each ruleset has a bypass list, and an enforcement mode: **Active** (violations
are refused), **Evaluate** (violations are recorded in the audit log but
allowed — a dry run), or **Disabled**. Every rule in the list is enforced by
the same evaluator at every seam ReasonOS controls — pushes to hosted
repositories, the merge button, and the branch buttons in the product. Pushes
to an imported project's external origin happen outside ReasonOS and are
governed by that host.

<Note>
  Signed-commit enforcement currently checks that a signature is *present*;
  verifying signatures against registered keys is still in progress.
</Note>

## Reviewing and landing changes

Changes land through **change requests** — ReasonOS's pull requests, computed
from its own copy of the repository so they work for any origin with no code
host connected. Open them from the Code section or let
[`rbs stack submit`](/workflow/stacks) open one per branch of a stack; review
happens on a single scrolling screen with commit-pinned threads and verdicts;
hosted repositories merge with one button, guarded by branch rules and
required checks.

The full flow — opening, reviewing, stacks, merging, and the cross-project
inbox — is on [Change requests](/platform/change-requests).