Oxygen for Visual Studio Code

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.

Requirements

• Visual Studio Code 1.137 or later.
• 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".

OxygenHub's conflict resolver also offers Resolve in VS Code. The link opens this extension, which switches your checkout to the conflict's bookmark (after asking), pulls it, and opens the file here.

Squash or rebase from a proposal's swimlanes

On a proposal's swimlane board in OxygenHub, drag a change onto another to plan a squash (into it) or a rebase (onto it). Apply in VS Code opens this extension. It confirms the plan, switches to the proposal's bookmark, pulls it, and rewrites the changes here, where they are signed with your key. It then offers to push the bookmark.

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.

Colours and getting started

The history graph and the file letters use Oxygen's own themeable colours: oxygen.lane1…oxygen.lane8 for the graph's lanes, plus oxygen.head, oxygen.workingCopy, oxygen.signed, oxygen.sealed, oxygen.invalid and oxygen.added/modified/removed/renamed/conflict/resolved. Set them under workbench.colorCustomizations. Get started with Oxygen, on the Welcome page, walks through a first repository. Oxygen: Create Identity… makes your signing key.

Settings

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.

Building

npm install
npm run check          # typecheck, bundle, and test against the oxy binary
npm run package        # oxygen-vscode-<version>.vsix
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.

Status

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.

Licence

MIT or Apache-2.0, at your option, as for Oxygen itself.