CVSA Lesson by Edgar A Stonehill Admittedly, not the best tool for writers, but the one I am most familiar with. ::Prelude:: For the majority of writers CVS is will not be the best revision tool because CVS has two limitations: 1) Designed to work with text files (not word documents). 2) Unable to (easily) rename files. These limitations can be overcome, but the ability to do so requires a more complicated understanding of the system than most people need to know. So why include a lesson on CVS? The answer is simple, it is the system that I learned first and have the greatest familiarity with. If I knew how I was going to use it, and how many times I changed a file name in the course of revising my work, I would have set up a Subversion system. But since all my work is in CVS, it will likely remain there. So the first part of the CVS lesson, is that writers are better off using Subversion. ::Installation:: CVS was originally designed for unix systems, and as a result works best with Linux operating systems (probably another limitation for writers). Installation across these systems varies, so all I can offer is the CVS's website A variant of CVS can be installed on Windows and Mac. The variant is call CVSNT. At the time this lesson was written, their website was down. The best link I can provide is their wikipedia entry. ::Setup:: All examples assume that the server and the client are the same machine. Since it is helpful for files and folders to not contain spaces, none of the files and folders used in the examples will have any. The examples cover the commands for the standard cvs client which has a text interface so it runs in the command window. For those of you who remember, this will look a lot like DOS. There are several alternatives for clients which provide a more familiar look and feel (like something similar to a file browser). A good one for windows is www.tortoisecvs.org An alternative that can be installed on both windows and mac is If you are running linux, then I consider you smart enough to find an evaluate a client on your own. I have tried neither of these clients listed above. Yes, that means I type all the commands on a regular basis. ::Manual:: There is a wikied manual for CVS. You can also access it by clicking the "Documentation" link on the CVS homepage. And then click the "manual" link. ::Repository:: The first thing that needs to be done is to create a repository. This will act as a central library for all your work and revisions. When editing your work you will *checkout* from the library to a different folder. 1) create the folder - best place for this is in your home folder (aka 'My Documents'). There standard is usually CVSROOT. 2) designate the folder as the repository - The command for creating the repository is called *init*. When using the standard text based client the command will look like this: cvs -d /home/[user-name]/CVSROOT init The -d option is short for directory. Directory is a fancy word for folder. The file path that follows -d follows a standard unix structure. The user name folder in the home folder is similar to a user's My Documents folder in windows. For the remainder of the examples the [user-name] will be "writer" and I assume that a default repository has been set. A server can have more than one repository, but for the most part writers are better off putting all their work into one repository. Personally, I use two repositories. One for my writings, and one for everything else. But I use the writing repository far more than the other one. ::Projects:: Next we need to add some writing projects to the repository. The first step is to create the folders and files outside of the repository and then import them. Separating out projects by writing style, type or genre are some possibilities So one project could be for poetry, another for short stories, another for novels, another for plays, and another for grocery lists. For this lesson, I will set up projects for poetry and short stories. Each project would then have a series of sub projects. Poetry, might be divided into the year written, while short stories might be divided by series and titles. In this scenario our poetry project would resemble a folder like this: poetry /2008 /2009 /2010 And the short story project could resemble this shortstory /AppetiteSeries /GoodAliensEatCabbage /TheDogWhoAteInfinity For the example, both the poetry and shortstory folders will be in a folder named "tmp" in the home directory. For each year in the poetry folder the poetry would be saved in text files. In otherwords, a file ending in the .txt extension. You are best off using a lightweight text editor to write these, because they will be more likely to save in that style. Examples of ightweight editors for windows would be wordpad or notepad. One called jEdit will work on most operating systems because it is based on java. jEdit's website is If you absolutely need formatting for your work are to save the files as a webpage (.html) or as a rich text format (.rtf). However, doing this will make the ability to compare revisions for differences extremely complicated. Comparing revisions is necessary for a process known as *branching*. Branching will allow a writer to explore different contingencies with the same work, and then adopt the one that writer prefers the most. Returning to the example, we have now put in all the text files for the poetry written in 2008 up through 2010. Additionally all the text files needed for the two short stories have been put into the appropriate folders. Now the commands First navagate to the folders you have created cd /home/writer/tmp/poetry The "cd" command is short for "change director" or in more human terms "open folder" (since it is in a command window, only one folder can be open at a time). Next use the cvs client to import the folder, subfolders, and text files. cvs import -m "creating poetry project" The -m is short for message and is optional. In this example all of the files getting imported will have the message "creating poetry project" in their log file, along with the date and time. If the -m option is not used cvs will launch a text editor. Anything typed in their will be applied to all of the files individual logs. Importing the short story project would resemble this (opting this time not to include a message, but instead will type one in the text editor. cd ../shortstory cvs import Now comes the part where it gets a little crazy. Delete the poetry and shortstory folders from the tmp folder. The work should be imported into the CVSROOT folder in very cryptic files that you should avoid editing. For now, just verify that the CVSROOT now has the poetry and shortstory subfolders. ::Backup:: To back up all your work, just create a zip file based on the CVSROOT folder. If you need a zip utility, I recommend 7zip. ::Checkout from the Repository:: Now lets edit some of our work. We're going edit the story "The Dog Who Ate Infinity". The following commands will assist you in this: cd /home/writer/tmp cvs checkout shortstory/ApetiteSeries/TheDogWhoAteInfinity A folder titled "shortstory" has been created in the "tmp" folder. It will have two folders in it. One will be titled "CVS" which should not be edited. The other will be TheDogWhoAteInfinity. To get a copy of the folder with out the "CVS" folder, use the *export* command. However, you lose all the revision features that cvs provides ::Revise:: Next do what writers do well - change your mind. Change anything within the files you have imported. When you are done use the following command (in the appropriate folder) cvs commit This will commit all of the changes made to the repository for all files edited. As with the init command you will can use the -m option for a short note. Omitting it will launch a text editor The -m option is best used when committing one file at a time. For instance we just changed two text files for the story. But I want to save a short message for one, and a detailed message in the other. The following commands will achieve that goal. cvs commit -m "fixed several typos" TheDog.txt cvs commit IntroducingInfinity.txt After the last command a text editor will launch and I will be able to write about what inspired me to include a new character in this revision. These messages can be accessed by using the *log* command. I recommend using it like this cvs log TheDog.txt > TheDog.log This will create a new text file with the extension .log. The new text file is not apart of the repository, and can be deleted at any time. It will contain information about the current revision number and most importantly two messages: 1) "Fixed several typos" 2) whatever was included in the message when the project was imported. As more revisions are made, these messages become increasingly valuable. A more consolidated form of the information is the status. To use it in the same way as the log command try this: cvs status TheDog.txt > TheDog.status ::Adding Files and Folders:: The log file that was generated is not added to the repository, nor should it be (it would be redundant). However, lets add a subfolder to keep information on the characters that will be developed. To do this, create a folder called "characters" cvs add characters This command is deceiving, it does not add it to the repository, but marks it to be included the next time the commit command is issued. So... cvs commit -m "adding folder for character development" characters Adding files is identical to adding folders to the repository. ::Tagging:: So after lots of revising the files for the story "The Dog Who Ate Infinity" we want to preserve each file in its current state. To do this, we will add a tag. In the folder TheDogWhoAteInfinty use the following command cvs tag "revision_01" Tags in the repository cannont have a space or a "." So something like: version 1.0 will be represented as: version1_0 Logical tags for revisions might be for submissions to publications, copyright or posting to a website like writerscafe.org. Then to revert back to a specific revision use the update command: cvs update -r revision_01 A file name can be applied after the command as well, if you only want to work with one file. To check out a specific revision use the command cvs checkout -r revision_01The -r option will also accept version numbers assigned by cvs. It would resemble something like 1.8 or 1.7.2.8. Both the tag names and cvs version numbers can be found in the logs for each file. ::Branching:: As I mentioned before branching is a process that will allow for contingencies. To do this will do a special type of commit. cvs commit -t AlternateEnding To be honest, this process has not always been successful for me, but here is the webpage I have been referencing. The example it offers is a misspelled nursery rhyme, and not a source code for a program (like most examples of cvs). In software programming branching is a technique used to solve one specific problem. Knowing this might come in handy when experimenting with this approach.   Comments |
Stats
1322 Views
0 Subscribers Added on February 11, 2010 Last Updated on February 28, 2010
Author
Edgar A StonehillAboutMy work is self published in booklets . Each week a new piece appears on my website http://edgarastonehill.com If you are interested in obtaining a copy of one of these booklets please send me a m.. |
Share This
Print
Subscribe
Flag Course