-`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.
-**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.
- 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.
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.
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.
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.
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.
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.
|`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`.
`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.