Pijul for VS Code

Experimental! Unofficial!

This is a community extension: it is not affiliated with or endorsed by the Pijul project.

Pijul is a distributed version control system that is easy to learn and use. This experimental beta-version extension provides access from VS Code to the essential features of Pijul:

• Initialize a Pijul repository directly from the Source Control view.
• Add, Reset, or Record one, some, or all of the files in the Pijul Repository.
• Channels: fork, switch, rename, delete, and merge channels.
• Changelog view listing recorded changes, with their TOML files and copy commands for hash and message.
• Remotes view listing the configured remotes.
• Decorations in the file tree indicating the current state of each file.
• VS Code comparison integration for diffing working files with their last recorded versions.
• Open and edit the repository or the global Pijul configuration.

Other operations need to be done using Pijul’s command line interface in a terminal.

What is Pijul?

Pijul is a free, open-source distributed version control system based on a mathematically sound theory of patches. Unlike Git, which snapshots files, Pijul models your repository as a graph of lines — which gives it some unique properties:

• Commutation: independent changes apply in any order with the same result — no rebase ceremony.
• Correct merges: the order between lines is always preserved; where order is genuinely unknown, Pijul shows a conflict instead of silently guessing.
• First-class conflicts: conflicts are just changes, resolved once and everywhere — they never come back.
• Partial clones: clone only the subset of a repo you need (great for monorepos).

Learn more

• Install Pijul — official installation instructions
• pijul.org — overview and why Pijul
• The Nest — repository hosting & the Pijul manual
• Theory of patches — how it works under the hood

Workspace trust

The extension executes the Pijul CLI on the contents of the workspace, so it only activates in trusted workspaces. While a workspace is restricted, the pijul.installationPath setting is only read from user settings, never from workspace settings.

Installation

This extension requires Pijul.

To install Pijul:

1. Install pijul (Tested with 1.0.0-beta.24)
2. Make sure that pijul is in the PATH: pijul --version
3. Create an identity: pijul identity new

To activate Pijul version control in a folder, run pijul init in the folder.

Install Pijul for VS Code from the VS Code Marketplace, or from the command line:

code --install-extension lale.pijul-vscode

Restart VSCode.

Alternatively, the extension can be built and installed from the source:

pijul clone https://nest.pijul.com/lale/pijul-vscode
cd pijul-vscode
npm install
npx vsce package
code --install-extension pijul-vscode-*.vsix

Feedback on this extension is welcome at the nest.

Contributing

Pijul for VS Code welcomes all contributions. Areas of development include:

• make all Pijul commands available from VS Code
• properly handle move and deletion of files
• show diff for past changes

To set-up your environment for the development of a VS Code Extension:

1. Install Node, e.g., using nvm:

nvm install node

2. Install dependencies

npm install

3. clone this repository:

pijul clone https://nest.pijul.com/lale/pijul-vscode
cd pijul-vscode

4. Add the following hook to your Pijul config file for linting:

[hooks]
record = ["npm run lint && npm run format:check"]

5. create a channel for your changes (not main)

pijul fork <your name>

6. test and build this extension, as in this example.

Tests

The test suite has two parts:

• Unit tests (npm run test:unit) cover the pure parsing helpers and type guards in plain Node, without VS Code.
• Integration tests (npm run test:integration) run the full extension in a VS Code test instance against a fixture workspace, exercising the SCM buttons, the views, and the channel operations. They require the pijul CLI on the PATH.

Run everything with:

npm test

To submit your change:

1. create an account on The Nest

2. create an SSH key if you don’t have one yet, and note where it is stored (e.g. ~/.ssh/id_rsa.pub)

3. copy your public SSH key to The Nest (possibly use cat ~/.ssh/id_rsa.pub to view it)

4. open a discussion on the repository page describing your change

5. push your change to that discussion, where main is the remote channel and the number is the discussion’s:

pijul push <your login>@ssh.pijul.com:lale/pijul-vscode --to-channel main:<discussion number>

If you have write access to the repository, you can also push directly, without a discussion:

pijul push <your login>@ssh.pijul.com:lale/pijul-vscode