Title : File versioning with rcs
Author: Solène
Date  : 31 October 2018
Tags  : openbsd68 highlight unix

In this article I will present you the [**rcs**](https://man.openbsd.org/rcs)
tools and we will use it for versioning files in /etc to track changes between
editions. These tools are part of the OpenBSD base install.  

## Prerequisites

You need to create a `RCS` folder where your files are, so the files
versions will be saved in it. I will use */etc* in the examples, you
can adapt to your needs.

    # cd /etc
    # mkdir RCS

The following examples use the command `ci -u`. This will be explained
later why so.


## Tracking a file

We need to add a file to the RCS directory so we can track its
revisions. Each time we will proceed, we will create a new *revision*
of the file which contain the whole file at that point of time. This
will allow us to see changes between revisions, and the date of each
revision (and some others informations).

I really recommend to track the files you edit in your system, or even
configuration file in your user directory.

In next example, we will create the first revision of our file with
[ci](https://man.openbsd.org/ci), and we will have to write some message about
it, like what is doing that file. Once we write the message, we need to
validate with a single dot on the line.

    # cd /etc
    # ci -u fstab
    fstab,v  <--  fstab
    enter description, terminated with single '.' or end of file:
    NOTE: This is NOT the log message!
    >> this is the /etc/fstab file
    >> .
    initial revision: 1.1
    done


## Editing a file

The process of edition has multiples steps, using
[ci](https://man.openbsd.org/ci) and [co](https://man.openbsd.org/co):

1. checkout the file and lock it, this will make the file available
   for writing and will prevent using `co` on it again (due to lock)
2. edit the file
3. commit the new file + checkout

When using `ci` to store the new revision, we need to write a small
message, try to use something clear and short. The log messages can be
seen in the file history, that should help you to know which change
has been made and why. The full process is done in the following
example.

    # co -l fstab
    RCS/fstab,v  -->  fstab
    revision 1.1 (locked)
    done
    # echo "something wrong" >> fstab
    # ci -u fstab
    RCS/fstab,v  <--  fstab
    new revision: 1.4; previous revision: 1.3
    enter log message, terminated with a single '.' or end of file:
    >> I added a mistake on purpose!
    >> .
    revision 1.4 (unlocked)
    done


## View changes since last version

Using previous example, we will use [rcsdiff](https://man.openbsd.org/rcsdiff)
to check the changes since the last version.

    # co -l fstab
    RCS/fstab,v  -->  fstab
    revision 1.1 (locked)
    done
    # echo "something wrong" >> fstab
    # rcsdiff -u fstab
    --- fstab	2018/10/28 14:28:29	1.1
    +++ fstab	2018/10/28 14:30:41
    @@ -9,3 +9,4 @@
     52fdd1ce48744600.j /usr/src ffs rw,nodev,nosuid 1 2
     52fdd1ce48744600.e /var ffs rw,nodev,nosuid 1 2
     52fdd1ce48744600.m /data ffs rw,dev,wxallowed,nosuid 1 2
    +something wrong

The `-u` flag is so to produce an unified diff, which I find easier to
read. Lines with `+` shows additions, and lines with `-` show
deletions (there are none in the example).


## Use of ci -u

The examples were using `ci -u` this is because, if you use `ci
some_file`, the file will be saved in the RCS folder but will be
missing in its place. You should use `co some_file` to get it back (in
read-only).

    # co -l fstab
    RCS/fstab,v  -->  fstab
    revision 1.1 (locked)
    done
    # echo "something wrong" >> fstab
    # ci -u fstab
    RCS/fstab,v  <--  fstab
    new revision: 1.4; previous revision: 1.3
    enter log message, terminated with a single '.' or end of file:
    >> I added a mistake on purpose!
    >> .
    done
    # ls fstab
    ls: fstab: No such file or directory
    # co fstab
    RCS/fstab,v  -->  fstab
    revision 1.5
    done
    # ls fstab
    fstab

Using `ci -u` is very convenient because it prevent the user to forget
to checkout the file after commiting the changes.


## Show existing revisions of a file

    # rlog fstab
    RCS file: RCS/fstab,v
    Working file: fstab
    head: 1.2
    branch:
    locks: strict
    access list:
    symbolic names:
    keyword substitution: kv
    total revisions: 2;     selected revisions: 2
    description:
    new file
    ----------------------------
    revision 1.2
    date: 2018/10/28 14:45:34;  author: solene;  state: Exp;  lines: +1 -0;
    Adding a disk
    ----------------------------
    revision 1.1
    date: 2018/10/28 14:45:18;  author: solene;  state: Exp;
    Initial revision
    =============================================================================

We have revisions 1.1 and 1.2, if we want to display the file in its
1.1 revision, we can use the following command:

    # co -p1.1 fstab
    RCS/fstab,v  -->  standard output
    revision 1.1
    52fdd1ce48744600.b none swap sw
    52fdd1ce48744600.a / ffs rw 1 1
    52fdd1ce48744600.l /home ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.d /tmp ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.f /usr ffs rw,nodev 1 2
    52fdd1ce48744600.g /usr/X11R6 ffs rw,nodev 1 2
    52fdd1ce48744600.h /usr/local ffs rw,wxallowed,nodev 1 2
    52fdd1ce48744600.k /usr/obj ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.j /usr/src ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.e /var ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.m /data ffs rw,dev,wxallowed,nosuid 1 2
    done

**Note that there is no space between the flag and the revision! This
is required.**

We can see that the command did output some extra informations about
the file and "*done*" at the end of the file. Thoses extra
informations are sent to stderr while the actual file content is sent
to stdout. That mean if we redirect stdout to a file, we will get the
file content.

    # co -p1.1 fstab > a_file
    RCS/fstab,v  -->  standard output
    revision 1.1
    done
    # cat a_file
    52fdd1ce48744600.b none swap sw
    52fdd1ce48744600.a / ffs rw 1 1
    52fdd1ce48744600.l /home ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.d /tmp ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.f /usr ffs rw,nodev 1 2
    52fdd1ce48744600.g /usr/X11R6 ffs rw,nodev 1 2
    52fdd1ce48744600.h /usr/local ffs rw,wxallowed,nodev 1 2
    52fdd1ce48744600.k /usr/obj ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.j /usr/src ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.e /var ffs rw,nodev,nosuid 1 2
    52fdd1ce48744600.m /data ffs rw,dev,wxallowed,nosuid 1 2


## Show a diff of a file since a revision

We can use **rcsdiff** using **-r** flag to tell it to show the
changes between last and one specific revision.

    # rcsdiff -u -r1.1 fstab
    --- fstab	2018/10/29 14:45:18	1.1
    +++ fstab	2018/10/29 14:45:34
    @@ -9,3 +9,4 @@
     52fdd1ce48744600.j /usr/src ffs rw,nodev,nosuid 1 2
     52fdd1ce48744600.e /var ffs rw,nodev,nosuid 1 2
     52fdd1ce48744600.m /data ffs rw,dev,wxallowed,nosuid 1 2
    +something wrong