{"header":{"message":"Record text for Pijul 0.12 as starting point","description":null,"timestamp":"2022-03-09T20:48:57.086891Z","authors":[{}]},"hash":"2FH6C6NN467AAQFV3TLOH6LLKW2XS7BBTMJNKQDSOLWV3KS5UYJQC","authors":[{"login":"tae","key":"BB9aMq7HXRMAty1CEyZAVJ5X6cTPBa3LbbvePQjwxMVr"}],"deps":{"hashes":[["2FH6C6NN467AAQFV3TLOH6LLKW2XS7BBTMJNKQDSOLWV3KS5UYJQC","Record text for Pijul 0.12 as starting point"],["AA",null],["YP4JAUCVWNUGTGKSOZYLAAJCNWNNAUJN45WBCAD6TF4C6V6BV5NAC",""]],"deps":["YP4JAUCVWNUGTGKSOZYLAAJCNWNNAUJN45WBCAD6TF4C6V6BV5NAC"],"known":[]},"hunks":[{"FileAdd":{"meta":{"basename":"README.md","metadata":0},"context":[{"change":2,"pos":1}],"contents":[{"Add":"# Pijul for Git users"},{"Add":""},{"Add":"## Introduction"},{"Add":""},{"Add":"Pijul is an in-development distributed version control system that"},{"Add":"implements repositories using a different [model][model] than"},{"Add":"Git's. This model enables [cool features][why-pijul] and avoids"},{"Add":"[common problems][bad-merge] which we are going to explore in this"},{"Add":"tutorial. (The good stuff appears from the \"Maybe we don't need"},{"Add":"branches\" section.) It is assumed that the reader uses Git in a"},{"Add":"daily base, i.e. knows not only how to commit, push and pull but"},{"Add":"also has had the need to cherry-pick commits and rebase branches"},{"Add":"at least once."},{"Add":""},{"Add":"## Creating a repo"},{"Add":""},{"Add":"```"},{"Add":"$ mkdir pijul-tutorial"},{"Add":"$ cd pijul-tutorial"},{"Add":"$ pijul init"},{"Add":"```"},{"Add":""},{"Add":"Nothing new here."},{"Add":""},{"Add":"## Adding files to the repository"},{"Add":""},{"Add":"Just like in Git after we create a file it must be explicitly"},{"Add":"added to the repository:"},{"Add":""},{"Add":"```"},{"Add":"$ pijul add "},{"Add":"```"},{"Add":""},{"Add":"There's a difference though: in Pijul a file is just a UNIX file,"},{"Add":"i.e. directories are also files so we don't need to create `.keep`"},{"Add":"files to add *empty* directories to our repos. Try this:"},{"Add":""},{"Add":"```"},{"Add":"$ mkdir a-dir"},{"Add":"$ touch a-dir/a-file"},{"Add":"$ pijul add a-dir/"},{"Add":"$ pijul status"},{"Add":"```"},{"Add":""},{"Add":"The output will be:"},{"Add":""},{"Add":"```"},{"Add":"On branch master"},{"Add":""},{"Add":"Changes not yet recorded:"},{"Add":" (use \"pijul record ...\" to record a new patch)"},{"Add":""},{"Add":" new file: a-dir"},{"Add":""},{"Add":"Untracked files:"},{"Add":" (use \"pijul add ...\" to track them)"},{"Add":""},{"Add":" a-dir/a-file"},{"Add":"```"},{"Add":""},{"Add":"To add files recursively we must use the `--recursive` flag."},{"Add":""},{"Add":"## Signing keys"},{"Add":""},{"Add":"Pijul can sign patches automatically, so let's create a signing key"},{"Add":"before we record our first patch:"},{"Add":""},{"Add":"```"},{"Add":"$ pijul key gen --signing"},{"Add":"```"},{"Add":""},{"Add":"The key pair will be located in `~/.local/share/pijul/config`. At"},{"Add":"the moment the private key is created without a password so treat"},{"Add":"it with care."},{"Add":""},{"Add":"## Recording patches"},{"Add":""},{"Add":"From the user perspective this is the equivalent to Git's commit"},{"Add":"operation but it is interactive by default:"},{"Add":""},{"Add":"```"},{"Add":"$ pijul record"},{"Add":""},{"Add":"added file a-dir"},{"Add":""},{"Add":"Shall I record this change? (1/2) [ynkadi?] y"},{"Add":""},{"Add":"added file a-dir/a-file"},{"Add":""},{"Add":"Shall I record this change? (2/2) [ynkadi?] y"},{"Add":""},{"Add":"What is your name ? Someone's name"},{"Add":"What is the name of this patch? Add a dir and a file"},{"Add":"Recorded patch 6fHCAzzT5UYCsSJi7cpNEqvZypMw1maoLgscWgi7m5JFsDjKcDNk7A84Cj93ZrKcmqHyPxXZebmvFarDA5tuX1jL"},{"Add":"```"},{"Add":""},{"Add":"Here `y` means yes, `n` means no, `k` means undo and remake last"},{"Add":"decision, `a` means include this and all remaining patches, `d`"},{"Add":"means include neither this patch nor the remaining patches and `i`"},{"Add":"means ignore this file locally (i.e. it is added to"},{"Add":"`.pijul/local/ignore`)."},{"Add":""},{"Add":"Let's change `a-file`:"},{"Add":""},{"Add":"```"},{"Add":"$ echo Hello > a-dir/a-file"},{"Add":""},{"Add":"$ pijul record"},{"Add":"In file \"a-dir/a-file\""},{"Add":""},{"Add":"+ Hello"},{"Add":""},{"Add":"Shall I record this change? (1/1) [ynkad?] y"},{"Add":""},{"Add":"What is the name of this patch? Add a greeting"},{"Add":"Recorded patch 9NrFXxyNATX5qgdq4tywLU1ZqTLMbjMCjrzS3obcV2kSdGKEHzC8j4i8VPBpCq8Qjs7WmCYt8eCTN6s1VSqjrBB4"},{"Add":"```"},{"Add":""},{"Add":"## Ignoring files"},{"Add":""},{"Add":"We saw that when recording a patch we can chose to locally ignore"},{"Add":"a file, but we can also create a `.pijulignore` or `.ignore` file"},{"Add":"in the root of our repository and record it. All those files"},{"Add":"accept the same patterns as a `.gitignore` file."},{"Add":""},{"Add":"Just like in Git if we want to ignore a file that was recorded in"},{"Add":"a previous patch we must remove that file from the repository."},{"Add":""},{"Add":"## Removing files from the repository"},{"Add":""},{"Add":"```"},{"Add":"$ pijul remove "},{"Add":"```"},{"Add":""},{"Add":"The files will be shown as untracked again whether they were"},{"Add":"recorded with a previous patch or not, so this has the effect of"},{"Add":"`git reset ` or `git rm --cached` depending on the previous"},{"Add":"state of these files."},{"Add":""},{"Add":"## Removing a patch"},{"Add":""},{"Add":"```"},{"Add":"$ pijul unrecord"},{"Add":"```"},{"Add":""},{"Add":"This command is interactive. Alternatively, one can use `pijul"},{"Add":"unrecord ` to remove one or more patches, knowing their hash."},{"Add":"Patch hashes can be obtained with `pijul log`."},{"Add":""},{"Add":"Unrecording and recording the same patch again will leave the"},{"Add":"repository in the same state."},{"Add":""},{"Add":"There are cases where a patch depends on a previous one."},{"Add":"For example if a patch edits (and only edits) file A it will"},{"Add":"depend on the patch that created that file. We can see these"},{"Add":"dependencies with `pijul dependencies` and they are managed"},{"Add":"automatically. This is why `pijul unrecord ` might"},{"Add":"sometimes refuse to work."},{"Add":""},{"Add":"## Discarding changes"},{"Add":""},{"Add":"```"},{"Add":"$ pijul revert"},{"Add":"```"},{"Add":""},{"Add":"This is like `git checkout` applied to files (instead of"},{"Add":"branches)."},{"Add":""},{"Add":"## Branches"},{"Add":""},{"Add":"To create a new branch we use the `pijul fork `"},{"Add":"command and to switch to another branch we use `pijul"},{"Add":"checkout `."},{"Add":""},{"Add":"To apply a patch from another branch we use the `pijul apply"},{"Add":"` command. Notice that this doesn't produce a"},{"Add":"different patch with a different hash like `git cherry-pick` does."},{"Add":""},{"Add":"Finally to delete a branch we have the `delete-branch` subcommand,"},{"Add":"but:"},{"Add":""},{"Add":"## Maybe we don't need branches"},{"Add":""},{"Add":"Because in Git each commit is related to a parent (except for the"},{"Add":"first one), branches are useful to avoid mixing up unrelated work."},{"Add":"We don't want our history to look like this:"},{"Add":""},{"Add":"```"},{"Add":"* More work for feature 3"},{"Add":"|"},{"Add":"* More work for feature 1"},{"Add":"|"},{"Add":"* Work for feature 3"},{"Add":"|"},{"Add":"* Work for feature 2"},{"Add":"|"},{"Add":"* Work for feature 1"},{"Add":"```"},{"Add":""},{"Add":"And if we need to push a fix for a bug ASAP we don't want to also"},{"Add":"push commits that still are a work in progress so we create"},{"Add":"branches for every new feature and work in them in isolation."},{"Add":""},{"Add":"But in Pijul patches usually commute: in the same way that 3 + 4 +"},{"Add":"8 produces exactly the same result than 4 + 3 + 8, if we apply"},{"Add":"patch B to our repo before we apply patch A and then C the result"},{"Add":"will be exactly the same that our coworkers will get if they apply"},{"Add":"patch A before patch C and then patch B. Now if patch C has a"},{"Add":"dependency called D (as we saw in Removing a patch) they cannot"},{"Add":"commute, but the entire graph commutes with other patches, i.e if"},{"Add":"I apply patch A before patch B and then patches CD I would get the"},{"Add":"same repository state than if I applied patch B before patches CD"},{"Add":"and then patch A. So Alice could have the same history as in the"},{"Add":"previous example while Bob could have"},{"Add":""},{"Add":"```"},{"Add":"* More work for feature 1"},{"Add":"|"},{"Add":"* Work for feature 2"},{"Add":"|"},{"Add":"* More work for feature 3"},{"Add":"|"},{"Add":"* Work for feature 3"},{"Add":"|"},{"Add":"* Work for feature 1"},{"Add":"```"},{"Add":""},{"Add":"And the repos would be equivalents; that is, the files would be the"},{"Add":"same. Why is that useful?"},{"Add":""},{"Add":"We can start working on a new feature without realizing"},{"Add":"that it is actually a new feature and that we need a new branch."},{"Add":"We can create all the patches we need for that feature (e.g. the"},{"Add":"patches that implement it, the patches that fix the bugs"},{"Add":"introduced by it, and the patches that fix typos) in whatever"},{"Add":"order we want. Then we can unrecord these patches and record them"},{"Add":"again as just one patch without a rebase. (There's actually no"},{"Add":"rebase operation in Pijul.)"},{"Add":""},{"Add":"But this model really shines when we start to work with:"},{"Add":""},{"Add":"## Remotes"},{"Add":""},{"Add":"At the moment, pushing works over SSH, the server only needs to have"},{"Add":"Pijul installed. [The Nest][nest] is a free service that hosts public"},{"Add":"repositories. We can reuse our current SSH key pair or create a new"},{"Add":"pair with"},{"Add":""},{"Add":"```"},{"Add":"$ pijul key gen --ssh"},{"Add":"```"},{"Add":""},{"Add":"This new key pair will be stored in the same directory used for"},{"Add":"the signing keys and we can add it to [The Nest][nest] like we do"},{"Add":"with SSH keys in GitHub."},{"Add":""},{"Add":"Now that we have an account on [The Nest][nest] we can upload our"},{"Add":"signing key with `pijul key upload`."},{"Add":""},{"Add":"Now let's push something:"},{"Add":""},{"Add":"```"},{"Add":"$ pijul push @nest.pijul.com:"},{"Add":"```"},{"Add":""},{"Add":"Unless we pass the `--all` flag Pijul will ask us which patches we"},{"Add":"want to push. So we can keep a patch locally, unrecord it, record"},{"Add":"it again, decide that actually we don't need it and kill it"},{"Add":"forever or push it a year later when we finally decide that the"},{"Add":"world needs it. All without branches."},{"Add":""},{"Add":"If we don't want to specify the remote every time we push we can"},{"Add":"set it as default with the `--set-default` flag."},{"Add":""},{"Add":"Of course to pull changes we have the `pijul pull` command."},{"Add":""},{"Add":"Both commands have `--from-branch` (source branch),"},{"Add":"`--to-branch` (destination branch) and `--set-remote` (create a"},{"Add":"local name for the remote) options."},{"Add":""},{"Add":"BTW if we can keep patches for ourselves can we pull only the"},{"Add":"patches we want? Yes, that's called \"partial clone\". [It was"},{"Add":"introduced in version 0.11][partial-clone] and works like this:"},{"Add":""},{"Add":"```"},{"Add":"$ pijul pull --path "},{"Add":"```"},{"Add":""},{"Add":"Of course it will bring the patch and all its dependencies."},{"Add":""},{"Add":"As we have seen we neither need branches, cherry-picking nor"},{"Add":"rebasing because of the patch theory behind Pijul."},{"Add":""},{"Add":"## Contributing with a remote"},{"Add":""},{"Add":"With Pijul we don't need forking either. The steps to contribute"},{"Add":"to a repo are:"},{"Add":""},{"Add":"1. Clone it with `pijul clone `"},{"Add":"2. Make some patches!"},{"Add":"3. Go to the page of the repo in [The Nest][nest] and open a"},{"Add":" new discussion"},{"Add":"4. [The Nest][nest] will create a branch with the number of the"},{"Add":" discussion as a name"},{"Add":"5. Push the patches with `pijul push"},{"Add":" @nest.pijul.com:/"},{"Add":" --to-branch :`"},{"Add":""},{"Add":"Then the repo owner could apply our patches to the master branch."},{"Add":"You can also attach patches from your repos to a discussion when"},{"Add":"you create or participate in one."},{"Add":""},{"Add":"## Tags"},{"Add":""},{"Add":"A tag in Pijul is a patch that specifies that all the previous"},{"Add":"patches depend on each other to recreate the current state of the"},{"Add":"repo."},{"Add":""},{"Add":"To create a tag we have the `pijul tag` command which will ask for"},{"Add":"a tag name."},{"Add":""},{"Add":"After new patches are added to the repo we can recreate the state"},{"Add":"of any tag by creating a new branch:"},{"Add":""},{"Add":"```"},{"Add":"pijul fork --patch

"},{"Add":"```"},{"Add":""},{"Add":"Because tags are just patches we can look for their hashes with"},{"Add":"`pijul log`."},{"Add":""},{"Add":"## In summary"},{"Add":""},{"Add":"Forget about bad merges, feature branches, rebasing and conflicts"},{"Add":"produced by merges after cherry-picking."},{"Add":""},{"Add":"## Learning more"},{"Add":""},{"Add":"[Pijul has an on-line manual][manual] but currently it is a"},{"Add":"little bit outdated. The best way to learn more is by"},{"Add":"executing `pijul help`. This will list all the subcommands and we"},{"Add":"can read more about any of them by running `pijul help"},{"Add":"`."},{"Add":""},{"Add":"The subcommands are interactive by default but we can pass data to"},{"Add":"them directly from the command line to avoid being asked"},{"Add":"questions. All these options are explained in each subcommand's help."},{"Add":""},{"Add":"For more information on the theory behind Pijul refer to Joe"},{"Add":"Neeman's [blog post on the matter][theory]. He also wrote a post"},{"Add":"[that explains how Pijul implements it][implementation]."},{"Add":""},{"Add":"## A work in progress"},{"Add":""},{"Add":"As we said Pijul is an in-development tool: [the UI could"},{"Add":"change in the future][ui-changes] and there are some missing"},{"Add":"features. ([Something][bisect] like `bisect` would be super"},{"Add":"helpful.) But that's also an opportunity: the developers seem"},{"Add":"quite open to [receive feedback][discourse]."},{"Add":""},{"Add":"[bad-merge]: https://tahoe-lafs.org/~zooko/badmerge/simple.html"},{"Add":"[bisect]: https://discourse.pijul.org/t/equivalent-of-checking-out-an-old-commit/176"},{"Add":"[discourse]: https://discourse.pijul.org"},{"Add":"[implementation]: https://jneem.github.io/pijul/"},{"Add":"[nest]: https://nest.pijul.com"},{"Add":"[manual]: https://pijul.org/manual/"},{"Add":"[model]: https://pijul.org/model/"},{"Add":"[partial-clone]: https://pijul.org/posts/2018-11-20-pijul-0.11/"},{"Add":"[theory]: https://jneem.github.io/merging/"},{"Add":"[ui-changes]: https://discourse.pijul.org/t/equivalent-of-checking-out-an-old-commit/176"},{"Add":"[why-pijul]: https://pijul.org/manual/why_pijul.html"}]}}],"owner":"tae","repo":"pijul-for-git-users","token":"EtZaRl9sDr9wyOK5QwlMN19SM8y13UxDaooGEr1hzro=","login":null}

…

Dependencies

Change contents