Add workflows chapter with page about channels

[?]

Dec 5, 2020, 11:20 AM

LYR3UWPMN2GBD5CKIB37RJM6TP5N5D4M2KF5VUZ2CIPTSPEISLBAC

Dependencies

[2] SCSV2FNS Reboot

Change contents

file addition: workflows.md (-xw-x--x--)

[2.6]

# Workflows

To give you a feeling of how `pijul` can be used in day-to-day situations, this
chapter collects a couple of scenarios and how they can be solved with `pijul`.

These scenarios hopefully also convey a way of thinking about Pijul concepts,
such as your repository, remote repositories, channels, changes, merges etc.

Most of these scenarios are taken from the Discourse forum hosted at
`discourse.pijul.org`.
file addition: workflows (dxwrx-rx-r)

[2.6]
file addition: channels.md (-xw-x--x--)

[0.451]

# Working with channels

## What is a channel

Channels are a way to maintain two related versions of a repository in the same
place (a bit like branches in Git).

Formally, a channel is a pointer to a set of changes (the state of a channel is
a set of changes).

However, channels are different from Git branches, and do not serve the same
purpose. In Pijul, independent changes commute, which means that in many cases
where branches are used in Git, there is no need to create a channel in Pijul.

The main differences with Git branches are:

* The identity of a change doesn't depend on the branch it is on, or in other
words, rebase and merge are the same operation in Pijul.
* This implies that conflicts do not mysteriously come back after you solve
them (which is what git rerere is for).
* Also, conflicts are between changes, so the resolution of a conflict on one
channel solves the same conflict in all other channels.

## What you can do with channels

### Creating a channel

A channel is created by using `pijul fork <new-channel>`. A succeeding command
does not issue any output.

### Listing channels

You can get a list of all channels with `pijul channel`:

```bash
me@host ~/pijul-test \$ pijul channel
* main
other
```

The currently active channel is marked with a `*` (asterisk).

### Switching channels

To work effectively with a channel, you need to be able to switch channels, so
that any changes you `pijul record` goes into the channel by default. This way,
there is no chance of forgetting the `--channel` option, for example. Long
story short, to change the channel, use

```bash
me@host ~/pijul-test \$ pijul channel switch other
```

Do not expect any output here, no news is good news!

### Merging channels

There is no simple way to merge all changes from one channel into another. This
being said, the usual workflow currently is:

```bash
me@host ~/pijul-test \$ pijul log --channel feature
Change EXKC67TCSWSPRG4JP5AK2MYSRG6RCC3N5W3N62KESUUFN3FN6R4AC
Author: []
Date: 2020-11-14 02:06:21.014281963 UTC

Some change

...
me@host ~/pijul-test \$ pijul apply EXKC67TCSWSPRG4JP5AK2MYSRG6RCC3N5W3N62KESUUFN3FN6R4AC
```

All changes this change depends upon will be applied as well.

### Deleting and renaming channels

You can delete a channel by using the command `pijul channel delete <channel>`.

Rename it with `pijul channel rename [<old>] <new>`, where `<old>` is optional
and defaults to the current channel.

NOTE: There seems to be a [bug](https://nest.pijul.com/pijul/pijul/discussions/163) (in 1.0.0-alpha.15) where the old channel is
still around after a rename.
edit in src/SUMMARY.md at line 18

[2.503772]

[2.503772]

- [Workflows](./workflows.md)
- [Channels](./workflows/channels.md)