If You Use Unix, Use Version Control
If you’ve used Unix (or Linux. This applies to Linux, and MacOS X, and probably various flavors of Windows as well), you’ve no doubt found yourself editing configuration files with a text editor. This is especially true if you’ve been administering a machine, either professionally or because you got roped into doing it.
And if you’ve been doing it for more than a day or two, you’ve made a mistake, and wished you could undo it, or at least see what things looked like before you started messing with them.
This is something that programmers have been dealing with for a long time, so they’ve developed an impressive array of tools to allow you to keep track of how a file has changed over time. Most of them have too much overhead for someone who doesn’t do this stuff full-time. But I’m going to talk about RCS, which is simple enough that you can just start using it.
Most programmers will tell you that RCS has severe limitations, like only being able to work on one file at a time, rather than a collection of files, that makes it unsuitable for use in all but a few special circumstances. Thankfully, Unix system administration happens to be one of those circumstances!
What’s version control?
Basically, it allows you to track changes to a file, over time. You check a file in, meaning that you want to keep track of its changes. Periodically, you check it in again, which is a bit like bookmarking a particular version so you can come back to it later. And you can check a file out, that is, retrieve it from the history archive. Or you can compare the file as it is now to how it looked one, five, or a hundred versions ago.
Note that RCS doesn’t record any changes unless you tell it to. That means that you should get into the habit of checking in your changes when you’re done messing with a file.
Starting out
Let’s create a file:
# echo "first" > myfile
Now let’s check it in, to tell RCS that we want to track it:
# ci -u myfile
myfile,v <-- myfile
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>> This is a test file
>> .
initial revision: 1.1
done
ci stands for “check in”, and is RCS’s tool for checking files in. The -u option says to unlock it after checking in.
Locking is a feature of RCS that helps prevent two people from stepping on each other’s toes by editing a file at the same time. We’ll talk more about this later.
Note that I typed in This is a test file. I could have given a description on multiple lines if I wanted to, but usually you want to keep this short: “DNS config file” or “Login message”, or something similar.
End the description with a single dot on a line by itself.
You’ll notice that you now have a file called myfile,v. That’s the history file for myfile.
Since you probably don’t want ,v files lying around cluttering the place up, know that if there’s a directory called RCS, the RCS utilities will look for ,v history files in that directory. So before we get in too deep, let’s create an RCS directory:
# mkdir RCS
Now delete myfile and start from scratch, above.
Done? Good. By the way, you could also have cheated and just moved the ,v file into the RCS directory. Now you know for next time.
Making a change
All right, so now you want to make a change to your file. This happens in three steps:
- Check out the file and lock it.
- Make the change(s)
- Check in your changes and unlock the file.
Check out the file:
# co -l myfile
RCS/myfile,v --> myfile
revision 1.1 (locked)
done
co is RCS’s check-out utility. In this case, it pulls the latest version out of the history archive, if it’s not there already.
The -l (lower-case ell) flag says to lock the file. This helps to prevent other people from working on the file at the same time as you. It’s still possible for other people to step on your toes, especially if they’re working as root and can overwrite anything, but it makes it a little harder. Just remember that co is almost always followed by -l.
Now let’s change the file. Edit it with your favorite editor and replace the word “first” with the word “second”.
If you want to see what has changed between the last version in history and the current version of the file, use rcsdiff:
# rcsdiff -u myfile
===================================================================
RCS file: RCS/myfile,v
retrieving revision 1.1
diff -u -r1.1 myfile
--- myfile 2016/06/07 20:18:12 1.1
+++ myfile 2016/06/07 20:32:38
@@ -1 +1 @@
-first
+second
The -u option makes it print the difference in “unified-diff” format, which I find more readable than the other possibilities. Read the man page for more options.
In unified-diff format, lines that were deleted are preceded with a minus sign, and lines that were added are preceded by a plus sign. So the above is saying that the line “first” was removed, and “second” was added.
Finally, let’s check in your change:
# ci -u myfile
RCS/myfile,v <-- myfile
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> Updated to second version.
>> .
done
Again, we were prompted to list the changes we made to the file (with a dot on a line by itself to mark the end of our text). You’ll want to be concise yet descriptive in this text, because these are notes you’re making for your future self when you want to go back and find out when and why a change was made.
Viewing a file’s history
Use the rlog command to see a file’s history:
# rlog myfile
RCS file: RCS/myfile,v
Working file: myfile
head: 1.2
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 2; selected revisions: 2
description:
Test file.
----------------------------
revision 1.2
date: 2016/06/07 20:36:52; author: arensb; state: Exp; lines: +1 -1
Made a change.
----------------------------
revision 1.1
date: 2016/06/07 20:18:12; author: arensb; state: Exp;
Initial revision
=============================================================================
In this case, there are two revisions: 1.1, with the log message “Initial revision”, and 1.2, with the log “Made a change.”.
Undoing a change
You’ve already see rlog, which shows you a file’s history. And you’ve seen one way to use rcsdiff.
You can also use either one or two -rrevision-number arguments, to see the difference between specific revisions:
# rcsdiff -u -r1.1 myfile
will show you the difference between revision 1.1 and what’s in the file right now, and
# rcsdiff -u -r1.1 -r1.2 myfile
will show you the difference between revisions 1.1 and 1.2.
(Yes, RCS will just increment the second number in the revision number, so after a while you’ll be editing revision 1.2486 of the file. Getting to revision 2.0 is an advanced topic that we won’t cover here.)
With the tools you already have, the simplest way to revert an unintended change to a file is simply to see what the file used to look like, and copy-paste that into a new revision.
Once you’re comfortable with that, you can read the manual and read up on things like deleting revisions with rcs -o1.2 myfile.
Checking in someone else’s changes
You will inevitably run into cases where someone changes your file without going through RCS. Either it’ll be a coworker managing the same system who didn’t notice the ,v file lying around, or else you’ll forget to check in your changes after making changes.
Here’s a simple way to see whether someone (possibly you) has made changes without your knowledge:
# co -l myfile
RCS/myfile,v --> myfile
revision 1.2 (locked)
writable myfile exists; remove it? [ny](n):
In this case, either you forgot to check in your changes, or else someone made the file writable with chmod, then (possibly) edited it.
In the former case, see what you did with rcsdiff, check in your changes, then check the file out again to do what you were going to do.
The latter case requires a bit more work, because you don’t want to lose your coworker’s changes, even though they bypassed version control.
- Make a copy of the file
- Check out the latest version of the file.
- Overwrite that file with your coworker’s version.
- Check those changes in.
- Check the file out and make your changes.
- Have a talk with your coworker about the benefits of using version control..
You already know, from the above, how to do all of this. But just to recap:
Move the file aside:
# mv myfile myfile.new
Check out the latest version:
# co -l myfile
Overwrite it with your coworker’s changes:
# mv myfile.new myfile
Check in those changes:
# ci -u myfile
RCS/myfile,v <-- myfile
new revision: 1.3; previous revision: 1.2
enter log message, terminated with single '.' or end of file:
>> Checking in Bob's changes:.
>> Route around Internet damage.
>> .
done
That should be enough to get you started. Play around with this, and I’m sure you’ll find that this is a huge improvement over what you’ve probably been using so far: a not-system of making innumerable copies of files when you remember to, with names like “file.bob”, “file.new”, “file.new2”, “file.newer”, and other names that mean nothing to you a week later.