README as walkthroughs by task with a settings table, dated changelog entries, and a test that the docs keep up with the manifest cdcffe39dd9f

// The documentation keeps up with the manifest: every setting is described

// in the README, and the CHANGELOG has a dated entry for this version.

import { test } from "node:test";

import assert from "node:assert/strict";

import { readFileSync } from "node:fs";

const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8");

const changelog = readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");

test("every setting is documented in the README's Settings table", () => {

  const cfg = pkg.contributes.configuration;

  const props = (Array.isArray(cfg) ? cfg : [cfg]).flatMap((c) => Object.keys(c.properties ?? {}));

  assert.ok(props.length > 0);

  const table = readme.slice(readme.indexOf("## Settings"));

  const missing = props.filter((p) => !table.includes("| `" + p + "` |"));

  assert.deepEqual(missing, [], "settings missing from the README");

});

test("the CHANGELOG's newest entry is this version, and every entry is dated", () => {

  const headings = [...changelog.matchAll(/^## (.+)$/gm)].map((m) => m[1]);

  assert.match(headings[0], new RegExp("^" + pkg.version.replace(/\./g, "\\.") + " \\(\\d{4}-\\d{2}-\\d{2}\\)$"));

  const undated = headings.filter((h) => !/^\d+\.\d+\.\d+ \(\d{4}-\d{2}-\d{2}\)$/.test(h));

  assert.deepEqual(undated, [], "entries without a version and date");

});

## 0.10.0 (2026-09-28)

## 0.9.0 (2026-09-28)

## 0.8.0 (2026-09-28)

## 0.7.1 (2026-09-28)

## 0.7.0 (2026-09-28)

Source control for Oxygen (`oxy`) repositories. It adds:

- a Source Control view with changes and conflicts

- diffs against the working copy's base and quick-diff gutters

- decorations in the explorer and a status bar item

- a history graph

- blame, bisect and trust views

- links to your forge

The design, milestone by milestone, is in `docs/spec.md` in this repository.

- `oxy` 0.1 or later. The extension looks for it in the `oxygen.path` setting first, then on your PATH, then at `~/.local/bin/oxy`.

- The extension drives `oxy --json` and never reads `.oxy/` itself, so anything it does, you can also do in a terminal.

## Getting started

1. Open a folder that is an Oxygen repository, or run **Oxygen: Initialize Repository** in a plain folder, or **Oxygen: Clone Repository** to start from a URL.

2. The Source Control view shows an **Oxygen** provider. The status bar shows the bookmark, the working copy and the state. Click it to switch, create, merge or delete bookmarks.

3. If you have no signing identity yet, the commit box says "unsigned: no identity". Run `oxy identity create` once in a terminal.

## Walkthroughs

### Commit

1. Edit files. They appear under **Changes**, with gutters in the editor and letters in the explorer.

2. Click a file to see its diff against the working copy's base.

3. Type a message in the commit box and press `Ctrl+Enter`. The box also tells you whether the change will be signed, sealed at push, or unsigned.

Variations:

- **Only some files:** right-click them and choose **Commit Selected**.

- **Only some hunks:** use **Commit Hunks…** from the view's menu. Anything a chosen hunk needs comes along with it.

- **Fix up the last change:** click the pencil in the view's title bar for **amend mode**. `Ctrl+Enter` then amends, and the box starts from the last change's message. Click the cross to leave amend mode.

- **Reuse a message:** **Previous Commit Messages…** puts a recent one back in the box.

If a file still holds conflict markers, whether Oxygen's or Git's, committing asks first and can open that file for you.

### Resolve a conflict

Conflicts are ordinary state in Oxygen. You can commit, push and pull them, and resolve them whenever you like.

1. Conflicted files appear under **Conflicts**.

2. In the editor, CodeLens actions above each marker accept one side, all sides, or a deletion.

3. For a conflict in the tree, such as two files given the same name, **Keep This Candidate** on the candidate you want.

4. Choose **Mark Resolved**, then commit. The commit box reads "Describe the resolution".

### Sync with a remote

- The status bar's sync counter shows changes to pull and to push. Click it to **Sync**.

- **Fetch**, **Pull**, **Push** and **Push Bookmark** are in the view's `…` menu.

- Pushing asks first unless `oxygen.confirmSync` is off.

### Read and rewrite history

1. **Show History** draws the bookmark's changes as a graph of dependencies. Independent changes sit side by side, and there are no merge nodes.

2. Click a change to diff it, check out its state, describe it, tag it or abandon it.

3. The same menu, or right-clicking a row, rewrites history:

   - **Split** a head: the files you choose become a separate first change.

   - **Squash** a change into one of its dependencies.

   - **Rebase** a change onto a bookmark, change or tag.

Every rewrite asks first and then offers **Undo**. The **Oxygen Operations** view can undo back to any point.

For one file:

- **File History** lists the changes that touched it, with diffs between versions.

- **Toggle Inline Blame** shows each line's change, author and age.

### Find a regression

The **Oxygen Bisect** view starts a bisection. Mark changes good, bad or skip, or give it a command to run. It shows the first bad change when it finds it.

### Link to lines on your forge

With a forge extension such as OxygenHub installed, right-click a line number, or inside the editor:

- **Open on Remote** opens the file at those lines.

- **Copy Remote Link** copies a link that follows the bookmark.

- **Copy Permalink** copies a link to the bookmark's current state, so it keeps showing these lines after later changes.

The link covers the line you clicked, or your selection. If the file has uncommitted edits, a note says the lines may not match the remote.

### Check trust

The **Oxygen Trust** view shows the repository's trust policy and each change's signature. **Verify Signatures** checks them all.

## Settings

| Setting | Default | What it does |

|---|---|---|

| `oxygen.path` | empty | Path to the `oxy` binary. Empty means `oxy` on PATH, then `~/.local/bin/oxy`. |

| `oxygen.autoRefresh` | `true` | Refresh the Source Control view when files in the workspace change. Off means refresh by hand. |

| `oxygen.decorations.enabled` | `true` | Status letters and colours in the explorer and on editor tabs. |

| `oxygen.inlineBlame` | `false` | Show each line's introducing change, author and age at the end of the line. Also toggled from the editor context menu. |

| `oxygen.confirmSync` | `true` | Ask before pushing. |

| `oxygen.showSnapshotOperations` | `false` | List snapshot operations in the Oxygen Operations view as well as commits, pulls and the rest. |

| `oxygen.statusBar.enabled` | `true` | Show the bookmark, working copy and state in the status bar. |

## For other extensions

The extension exports an API (`OxygenAPI`, version 1) with the repositories, their status and bookmarks, and a way to register a remote provider. It is what lets OxygenHub, or any forge, answer **Open on Remote**. See `src/api.ts`.

code --install-extension oxygen-vscode-<version>.vsix

`npm run watch` rebuilds on change. Press F5 in VS Code to launch an Extension Development Host with the bundle. The tests run the real `oxy`; set `OXY_BIN` to choose which one.

The spec's milestones 0.1 to 0.6 are done, and so are the additions listed in CHANGELOG.md. Left for 1.0: tests on macOS and Windows, a Marketplace publisher, and the spec's open questions.