| 1 |
# Oxygen for Visual Studio Code |
| 2 |
|
| 3 |
Source control for Oxygen (`oxy`) repositories. It adds: |
| 4 |
|
| 5 |
- a Source Control view with changes and conflicts |
| 6 |
- diffs against the working copy's base and quick-diff gutters |
| 7 |
- decorations in the explorer and a status bar item |
| 8 |
- a history graph |
| 9 |
- blame, bisect and trust views |
| 10 |
- links to your forge |
| 11 |
|
| 12 |
The design, milestone by milestone, is in `docs/spec.md` in this repository. |
| 13 |
|
| 14 |
## Requirements |
| 15 |
|
| 16 |
- Visual Studio Code 1.137 or later. |
| 17 |
- `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`. |
| 18 |
- The extension drives `oxy --json` and never reads `.oxy/` itself, so anything it does, you can also do in a terminal. |
| 19 |
|
| 20 |
## Getting started |
| 21 |
|
| 22 |
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. |
| 23 |
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. |
| 24 |
3. If you have no signing identity yet, the commit box says "unsigned: no identity". Run `oxy identity create` once in a terminal. |
| 25 |
|
| 26 |
## Walkthroughs |
| 27 |
|
| 28 |
### Commit |
| 29 |
|
| 30 |
1. Edit files. They appear under **Changes**, with gutters in the editor and letters in the explorer. |
| 31 |
2. Click a file to see its diff against the working copy's base. |
| 32 |
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. |
| 33 |
|
| 34 |
Variations: |
| 35 |
|
| 36 |
- **Only some files:** right-click them and choose **Commit Selected**. |
| 37 |
- **Only some hunks:** use **Commit Hunks…** from the view's menu. Anything a chosen hunk needs comes along with it. |
| 38 |
- **Fix up the last change with only some files:** right-click them and choose **Amend Selected Paths**. |
| 39 |
- **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. |
| 40 |
- **Reuse a message:** **Previous Commit Messages…** puts a recent one back in the box. |
| 41 |
|
| 42 |
If a file still holds conflict markers, whether Oxygen's or Git's, committing asks first and can open that file for you. |
| 43 |
|
| 44 |
### Resolve a conflict |
| 45 |
|
| 46 |
Conflicts are ordinary state in Oxygen. You can commit, push and pull them, and resolve them whenever you like. |
| 47 |
|
| 48 |
1. Conflicted files appear under **Conflicts**. |
| 49 |
2. In the editor, CodeLens actions above each marker accept one side, all sides, or a deletion. |
| 50 |
3. For a conflict in the tree, such as two files given the same name, **Keep This Candidate** on the candidate you want. |
| 51 |
- A binary file or subrepo pin changed two ways has no markers: **Keep a Side…** on it keeps one side's version. |
| 52 |
- Where two changes only added lines at the same place, **Keep Both Sides…** keeps every side, earliest change first. Oxygen leaves the markers where the sides changed the same lines and says so. |
| 53 |
- **Commit Resolution of Selected Paths** commits what you have resolved so far and leaves the rest for later. |
| 54 |
4. Choose **Mark Resolved**, then commit. The commit box reads "Describe the resolution". |
| 55 |
|
| 56 |
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. |
| 57 |
|
| 58 |
### Squash or rebase from a proposal's swimlanes |
| 59 |
|
| 60 |
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. |
| 61 |
|
| 62 |
### Sync with a remote |
| 63 |
|
| 64 |
- The status bar's sync counter shows changes to pull and to push. Click it to **Sync**. |
| 65 |
- **Fetch**, **Pull**, **Push** and **Push Bookmark** are in the view's `…` menu. |
| 66 |
- Pushing asks first unless `oxygen.confirmSync` is off. |
| 67 |
- **Merge Bookmark…** also lists remotes' bookmarks, such as `origin/develop`, as last fetched. |
| 68 |
- **Clone Repository…** offers a **Shallow** clone (latest state only) for big repositories. |
| 69 |
|
| 70 |
### Read and rewrite history |
| 71 |
|
| 72 |
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. |
| 73 |
2. Click a change to diff it, check out its state, describe it, tag it or abandon it. |
| 74 |
3. The same menu, or right-clicking a row, rewrites history: |
| 75 |
- **Split** a head: the files you choose become a separate first change. |
| 76 |
- **Squash** a change into one of its dependencies. |
| 77 |
- **Rebase** a change onto a bookmark, change or tag. |
| 78 |
|
| 79 |
Every rewrite asks first and then offers **Undo**. The **Oxygen Operations** view can undo back to any point. |
| 80 |
|
| 81 |
For one file: |
| 82 |
|
| 83 |
- **File History** lists the changes that touched it, with diffs between versions. |
| 84 |
- **Toggle Inline Blame** shows each line's change, author and age. |
| 85 |
|
| 86 |
### Find a regression |
| 87 |
|
| 88 |
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. |
| 89 |
|
| 90 |
### Link to lines on your forge |
| 91 |
|
| 92 |
With a forge extension such as OxygenHub installed, right-click a line number, or inside the editor: |
| 93 |
|
| 94 |
- **Open on Remote** opens the file at those lines. |
| 95 |
- **Copy Remote Link** copies a link that follows the bookmark. |
| 96 |
- **Copy Permalink** copies a link to the bookmark's current state, so it keeps showing these lines after later changes. |
| 97 |
|
| 98 |
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. |
| 99 |
|
| 100 |
### Check trust |
| 101 |
|
| 102 |
The **Oxygen Trust** view shows the repository's trust policy and each change's signature. **Verify Signatures** checks them all. **Verify Transparency Log** checks that your hub shows everyone the same history. The view then shows the checkpoint it verified and the witnesses who cosigned it. |
| 103 |
|
| 104 |
**Withdraw Tag…**, also in **Tags…**, withdraws a tag. The withdrawal is signed and kept, and push sends it on. The tag's name can't be used again. |
| 105 |
|
| 106 |
## Colours and getting started |
| 107 |
|
| 108 |
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. |
| 109 |
|
| 110 |
## Settings |
| 111 |
|
| 112 |
|
| 113 |
|
| 114 |
| `oxygen.path` | empty | Path to the `oxy` binary. Empty means `oxy` on PATH, then `~/.local/bin/oxy`. | |
| 115 |
| `oxygen.autoRefresh` | `true` | Refresh the Source Control view when files in the workspace change. Off means refresh by hand. | |
| 116 |
| `oxygen.decorations.enabled` | `true` | Status letters and colours in the explorer and on editor tabs. | |
| 117 |
| `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. | |
| 118 |
| `oxygen.confirmSync` | `true` | Ask before pushing. | |
| 119 |
| `oxygen.showSnapshotOperations` | `false` | List snapshot operations in the Oxygen Operations view as well as commits, pulls and the rest. | |
| 120 |
| `oxygen.statusBar.enabled` | `true` | Show the bookmark, working copy and state in the status bar. | |
| 121 |
|
| 122 |
## For other extensions |
| 123 |
|
| 124 |
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`. |
| 125 |
|
| 126 |
## Building |
| 127 |
|
| 128 |
``` |
| 129 |
npm install |
| 130 |
npm run check # typecheck, bundle, and test against the oxy binary |
| 131 |
npm run package # oxygen-vscode-<version>.vsix |
| 132 |
code --install-extension oxygen-vscode-<version>.vsix |
| 133 |
``` |
| 134 |
|
| 135 |
`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. |
| 136 |
|
| 137 |
## Status |
| 138 |
|
| 139 |
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. |
| 140 |
|
| 141 |
## Licence |
| 142 |
|
| 143 |
MIT or Apache-2.0, at your option, as for Oxygen itself. |