pijul_org / pijul

Updating the README

By blabla on February 25, 2019
This patch is not signed.
BBapoVTikXVuE9axYzLQzsd2NTWK64Bnn8fvr5cWUFCMKPeXRCGBHE6xk7TcPXFk3rAku3EKkzePd7uh9eZo9mTJ
This patch is in the following branches:
latest
master
testing
In file README.md

1
















2
3
4
5
6
7
8
9
10

11
12
13
14

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38






39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

58
59
60
61
62
63


64
65
3. Push it to the Nest. It is *not* necessary (and actually not even useful) to fork the project on the Nest, as changes can be pushed directly to discussions. After creating a discussion, one can push a patch directly to the corresponding branch. For instance, discussion 271 has branch name "#271", and patches can be pushed using:
# Pijul

Pijul is a version control system based on *patches*, that can mimic
the behaviour and workflows of both [Git](https://git-scm.org) and
[Darcs](http://darcs.net), but contrarily to those systems, Pijul is
based on a **mathematically sound theory of patches**.
based on a **mathematically sound theory of patches**.


Pijul was started out of frustration that no version control system
was at the same time fast and sound:

- Git has non-associative merges, which might lead to security problems. Concretely, this means that the commits you merge might not be the same as the ones you review and test. [More details here](https://nest.pijul.com/help/patches.html).

- Handling of conflicts: Pijul has an explicit internal representation of conflicts, a rock-solid theory of how they behave, and super-fast data structures to handle them.

- Speed! The complexity of Pijul is low in all cases, whereas previous attempts to build a mathematically sound distributed version control system had huge worst-case complexities. The use of [Rust](//www.rust-lang.org) additionally yields a blazingly fast implementation.

Pijul is a version control system based on *patches*. Its fundamental promise is that two patches producible in parallel always commute. This makes the whole system more correct, and much simpler to use, as explained [in the manual](https://pijul.org/manual/why_pijul.html).

## License

The license is GPL2, or any later version at your convenience. This was changed from the time when Pijul was still a prototype, and had another license.

## Getting Started

Pijul depends on [libsodium](https://libsodium.org) and [openssl](https://www.openssl.org/).
Pijul depends on [libsodium](https://libsodium.org) and [openssl](https://www.openssl.org/). They are not always easy to install. On Unix platforms, we recommend [the Nix package manager](https://nixos.org/nix/download.html) to start hacking on Pijul.

There are packages for a number of platforms, including [NixOS](https://nixos.org), [Brew](https://formulae.brew.sh/formula/pijul) for OSX, [our own builds](https://pijul.org/downloads) for Windows, [Aur](https://aur.archlinux.org/packages/pijul/) for Arch Linux, among others.

You can find Pijul on [crates.io](https://crates.io/crates/pijul). The easiest way to install it is to use cargo:
With the latest stable Rust installed, Pijul can also be compiled and installed using:

``` .shell
cargo install --force pijul
```

The `--force` flag is used so you can upgrade Pijul if you have a previous version already installed. Once the command has been executed, you can find the `pijul` binary in `~/.cargo/bin/`. You might want to add an alias in your shell profile.

Pijul looks for its configuration in `$PIJUL_CONFIG_DIR` first, then in `$HOME/.pijulconfig` if the former is not set.

## Community

[Our website](https://pijul.org/community) has instructions on how to reach out.

## Feature or bug?

Pijul, like any software, has bugs. In the past, some users have started believing that our bugs are "design choices", and have blamed us for our poor decisions.

If this happens to you, the best thing to do is to talk to us. The Pijul team strongly believes in positive criticism. If you believe something doesn't behave as expected, if the code looks "complex", if you don't understand the documentation, please reach out.

In most cases, it is a bug. In some others, there are very good reasons for some design choices. It might be the case that we found counter-intuitive examples in the past, that break more "natural" or "naive" approaches.

## Contributing

We welcome contributions, even if you understand nothing of patch theory.
Currently, the main areas where Pijul needs improvements are:

- Portable handling of SSH keys (Windows and Linux).
- Error messages. There are very few useful messages at the moment.
- HTTP Redirects and errors.
We welcome contributions, even if you understand nothing of patch theory. See the discussions in this repository to find tasks to do.

The first step towards contributing is to *clone the repositories*. Pijul depends on a number of packages maintained by the same team, the two largest ones being [Sanakirja](/pijul_org/sanakirja) and [Thrussh](/pijul_org/thrussh).
Here is how to build and install the pijul repositories:

``` .shell
$ pijul clone https://nest.pijul.com/pijul_org/pijul
$ cd pijul
$ cargo build
```

If you want to replace the version installed by Cargo with you own build, it is as simple as:

``` .shell
$ cargo install --force --path pijul
```

By contributing, you agree to make all your contributions GPL2+.

Moreover, the main platform for contributing is [the Nest](//nest.pijul.com/pijul_org/pijul), which is still experimental. Therefore, even though we do our best to avoid it, our repository might be reset, causing the patches of all contributors to be merged. Feel free to add your name in CONTRIBUTORS.md.
Moreover, the main platform for contributing is [the Nest](//nest.pijul.com/pijul_org/pijul), which is still somewhat experimental. Therefore, even though we do our best to avoid it, our repository might be reset, causing the patches of all contributors to be merged. Feel free to add your name in CONTRIBUTORS.md.

If you want to propose a change, you should proceed as follows:

1. Create a [new discussion on the Nest](https://nest.pijul.com/pijul_org/pijul/discussions), to gather feedback on your proposal.
2. Make your change, record a patch (by using `pijul record`).
3. Push it to the Nest. You do not need to create a fork on the Nest, as you would on GitHub for instance, to propose a change. You can actually “push your change” directly to the discussion. When you created your discussion, it got assigned a number. If this number is, for instance, 271, then you can propose a change by pushing to the branch `#272`, just like that:
3. Push it to the Nest. You do not need to create a fork on the Nest, as you would on GitHub for instance, to propose a change. You can actually “push your change” directly to the discussion. When you created your discussion, it got assigned a number. If this number is, for instance, 271, then you can propose a change by pushing to the branch `#272`, just like that:
3. Push it to the Nest. It is *not* necessary (and actually not even useful) to fork the project on the Nest, as changes can be pushed directly to discussions. After creating a discussion, one can push a patch directly to the corresponding branch. For instance, discussion 271 has branch name ":271", and patches can be pushed using: