| 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:** 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. |
| 39 |
- **Reuse a message:** **Previous Commit Messages…** puts a recent one back in the box. |
| 40 |
|
| 41 |
If a file still holds conflict markers, whether Oxygen's or Git's, committing asks first and can open that file for you. |
| 42 |
|
| 43 |
### Resolve a conflict |
| 44 |
|
| 45 |
Conflicts are ordinary state in Oxygen. You can commit, push and pull them, and resolve them whenever you like. |
| 46 |
|
| 47 |
1. Conflicted files appear under **Conflicts**. |
| 48 |
2. In the editor, CodeLens actions above each marker accept one side, all sides, or a deletion. |
| 49 |
3. For a conflict in the tree, such as two files given the same name, **Keep This Candidate** on the candidate you want. |
| 50 |
4. Choose **Mark Resolved**, then commit. The commit box reads "Describe the resolution". |
| 51 |
|
| 52 |
### Sync with a remote |
| 53 |
|
| 54 |
- The status bar's sync counter shows changes to pull and to push. Click it to **Sync**. |
| 55 |
- **Fetch**, **Pull**, **Push** and **Push Bookmark** are in the view's `…` menu. |
| 56 |
- Pushing asks first unless `oxygen.confirmSync` is off. |
| 57 |
|
| 58 |
### Read and rewrite history |
| 59 |
|
| 60 |
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. |
| 61 |
2. Click a change to diff it, check out its state, describe it, tag it or abandon it. |
| 62 |
3. The same menu, or right-clicking a row, rewrites history: |
| 63 |
- **Split** a head: the files you choose become a separate first change. |
| 64 |
- **Squash** a change into one of its dependencies. |
| 65 |
- **Rebase** a change onto a bookmark, change or tag. |
| 66 |
|
| 67 |
Every rewrite asks first and then offers **Undo**. The **Oxygen Operations** view can undo back to any point. |
| 68 |
|
| 69 |
For one file: |
| 70 |
|
| 71 |
- **File History** lists the changes that touched it, with diffs between versions. |
| 72 |
- **Toggle Inline Blame** shows each line's change, author and age. |
| 73 |
|
| 74 |
### Find a regression |
| 75 |
|
| 76 |
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. |
| 77 |
|
| 78 |
### Link to lines on your forge |
| 79 |
|
| 80 |
With a forge extension such as OxygenHub installed, right-click a line number, or inside the editor: |
| 81 |
|
| 82 |
- **Open on Remote** opens the file at those lines. |
| 83 |
- **Copy Remote Link** copies a link that follows the bookmark. |
| 84 |
- **Copy Permalink** copies a link to the bookmark's current state, so it keeps showing these lines after later changes. |
| 85 |
|
| 86 |
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. |
| 87 |
|
| 88 |
### Check trust |
| 89 |
|
| 90 |
The **Oxygen Trust** view shows the repository's trust policy and each change's signature. **Verify Signatures** checks them all. |
| 91 |
|
| 92 |
## Settings |
| 93 |
|
| 94 |
|
| 95 |
|
| 96 |
| `oxygen.path` | empty | Path to the `oxy` binary. Empty means `oxy` on PATH, then `~/.local/bin/oxy`. | |
| 97 |
| `oxygen.autoRefresh` | `true` | Refresh the Source Control view when files in the workspace change. Off means refresh by hand. | |
| 98 |
| `oxygen.decorations.enabled` | `true` | Status letters and colours in the explorer and on editor tabs. | |
| 99 |
| `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. | |
| 100 |
| `oxygen.confirmSync` | `true` | Ask before pushing. | |
| 101 |
| `oxygen.showSnapshotOperations` | `false` | List snapshot operations in the Oxygen Operations view as well as commits, pulls and the rest. | |
| 102 |
| `oxygen.statusBar.enabled` | `true` | Show the bookmark, working copy and state in the status bar. | |
| 103 |
|
| 104 |
## For other extensions |
| 105 |
|
| 106 |
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`. |
| 107 |
|
| 108 |
## Building |
| 109 |
|
| 110 |
``` |
| 111 |
npm install |
| 112 |
npm run check # typecheck, bundle, and test against the oxy binary |
| 113 |
npm run package # oxygen-vscode-<version>.vsix |
| 114 |
code --install-extension oxygen-vscode-<version>.vsix |
| 115 |
``` |
| 116 |
|
| 117 |
`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. |
| 118 |
|
| 119 |
## Status |
| 120 |
|
| 121 |
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. |
| 122 |
|
| 123 |
## Licence |
| 124 |
|
| 125 |
MIT or Apache-2.0, at your option, as for Oxygen itself. |