## Atomically swapping boot configuration

At this point, a new deployment directory has been created as a hardlink farm; the running system is untouched, and the bootloader configuration is untouched. We want to add this deployment to the "deployment list".

To support a more general case, OSTree supports atomic transitioning between arbitrary sets of deployments, with the restriction that the currently booted deployment must always be in the new set. In the normal case, we have exactly one deployment, which is the booted one, and we want to add the new deployment to the list. A more complex command might allow creating 100 deployments as part of one atomic transaction, so that one can set up an automated system to bisect across them.

## The bootversion

OSTree allows swapping between boot configurations by implementing the "swapped directory pattern" in `/boot`. This means it is a symbolic link to one of two directories `/ostree/boot.`[0|1]``. To swap the contents atomically, if the current version is `0`, we create `/ostree/boot.1`, populate it with the new contents, then atomically swap the symbolic link. Finally, the old contents can be garbage collected at any point.

## The /ostree/boot directory

However, we want to optimize for the case where we the set of kernel/initramfs pairs is the same between both the old and new deployment lists. This happens when doing an upgrade that does not include the kernel; think of a simple translation update. OSTree optimizes for this case because on some systems `/boot` may be on a separate medium such as flash storage not optimized for significant amounts of write traffic.

To implement this, OSTree also maintains the directory `/ostree/boot.`bootversion``, which is a set of symbolic links to the deployment directories. The `bootversion` here must match the version of `/boot`. However, in order to allow atomic transitions of this directory, this is also a swapped directory, so just like `/boot`, it has a version of `0` or `1` appended.

Each bootloader entry has a special `ostree=` argument which refers to one of these symbolic links. This is parsed at runtime in the initramfs.