Web Site
Developers
Using a Source Control System*
First Steps
I began this exercise of the selection and use of a version (source) control system with a very tentative set of actions, primarily due to my inexperience with the administrative functions of this sort of tool. I valued the ability to make errors without the necessity of a long recovery process, hence, my choosing Subversion. To date, I have not regretted my choice, despite at times resorting to shell commands to restructure my copy by hand. I have since learned I could have used subverion commands. Moreover, as I will show below I have taken many other actions with the working copy that are allowed without adverse consequence. Essentially, as long as I inform the stored, archived version in the repository prior to my making the commit I can create any sort of mess I desire and suffer no harm. [Not completely true, with the current site, BST Web Site Developers I ran into repeated failures to commit. The repository knew of many directories that were down as to be newly added. Reverting or removing the offending directories and later forced to take out subdirectories with new contents failed on retry. Nonetheless, I recovered by just building a new repository and beginning afresh, albeit, from a much later initial stage. Can't win the all.]
The content this time will be on the topics aluded to above, stopping just short of the commit action. There will be, however, one short digression where I wonder aboutemacs ../Desktop/ the meaning of the terms used describing what this sort of version control system makes its commits.
Atomic Commits - A Digression
As I mentioned in the first article in this series I had experience with version control systems that worked at the file level. To me, a file with a single or few changes would be atomic. Nonetheless, again counter to my experience and training atomic here means the entire project is rejected where a single change conflicts with a previous commit by another programmer. Moreover, in Subversion includes every file in the new version, including many or most having no change. This has not been the only instance where I have encountered a familar term attached to an alien concept. The take away point is that under Subversion you get the entire project and each commit updates every file to a new version number. Seems odd to me, but that's the way they do it. Consider yourself properly warned if you end up too using a source control system similar to Subversion (e.g. vcs). Others like ClearCase, when I used it seemed to be only file change oriented.
A Few Small Problems
I encounted this problem several times unexpectedly until I learned how to correct it. Here is an example command where I encountered, I hope, for the last time:
:~$ svn add images svn: '.' is not a working copy
Solve it by moving into your working copy directory:
:~$ cd OST-1/
No longer got that error, but my suspicion about the meaning of the proper interpretation of the manual's command appeared warrented:
:~/OST-1$ svn add images svn: warning: 'images' not found
But the manual said: "svn add foo", which to someone that has never taken a computer science course has a certain ambiguity about it. So it can mean it includes a path or directory structure. OK, let's try that:
:~/OST-1$ svn add ceo/images A ceo/images :~/OST-1$ svn add ceo/articles A ceo/articles A ceo/articles/EU-climate-I.html
So that is how you add directories and files that were not part of the original repository created from a base set. Once this is run at the time of committing your changes, the added directories and associated files becomes a part of the next version. In a sense, Subversion has been informed of your intentions.
A Few Other Details
There a number of subversion commands I did not use that are very similar to the add command above. The delete just removes directories and files that are no longer wanted or needed in the next version. Some of the others are: copy, move, and mkdir. Indeed, i created my own directories afterwards using the shell command line, then informed Subversion of their existence using the add command. Without direct experience with the other commands, I suggest you read the documentation (for Subversion) rather than my reguritating their writeup. Let us move on to other commands and results I deem of more important in preparing the working version for the committing into the repository.
The Subversion status command provides the user a picture all affected files. Running the simple status command without an option is the best way of getting the most concise picture of the changes that you have made on your working copy. Here is what mine looked like at an early stage:
:~/OST-1$ svn status A howto/images A howto/articles A howto/articles/HowTo-VersionControl-I.html M howto/HowTo-template.html A ceo/images A ceo/articles A ceo/articles/EU-climate-I.html M ceo/ceo-template-page.html
The 'A' denotes added and 'M' means modified. There are other possibilities, e.g. 'D' for a scheduled deletion and 'C', where this required more active users, meaning other changes made between versions are in conflict. Presently, this is of no concern to me, but you should be aware it can happen with multiple developers working on the same project.
The status command can supply quite a bit more information about your working copy if it is run with the verbose option. Now you see all components, even those that have not been modified, here is a truncated version where I leave more out than is shown:
:~/OST-1$ svn status -v
...
A 0 ? ? ceo/articles
A 0 ? ? ceo/articles/EU-climate-I.html
M 1 1 owner ceo/ceo-template-page.html
1 1 owner floss
1 1 owner floss/OSS-template.html
1 1 owner index
1 1 owner css
1 1 owner css/style-sheet.css
...
The first column tells what action, if anything, was done to the file. Note most are blank, meaning there has been no changes to the working copy. The second column is the version number, where zero denotes a pre-copy prior to be added to the repository, the third column is the last version this file was changed, the fourth is the identity of the person making the change and the last column is the directory or file in question. The question marks are due to Subversion not knowing the origin and owner. The reason for Subversion's ignorance, is that I used the shell commands to create and add files. Next time I will likely use the system tools.
As you approach the point where you think you have made the changes sufficient to create a new version, it is best to confirm the changes are exactly what you intended. The diff command in Subersion really impressed me, however, this seems to have been due to my employing the incorrect command under Linux where recently I used the week comm (compare) command where a much more robust version of diff exists on both Unix and Linux. Nonetheless, I really like diff where the output can be redirected to an external file, useful for later careful examination. Do not use the diff command without the redirection, because with several new files and modifications you could easily exceed the memory allotted on your terminal window.
While the diff commands are good in the shell, the output is very clear in Subversion with the minus sign indicating lines removed from the repostitory version and the plus sign indicating lines added. Unmarked lines represent unchanged lines. Please note that you can send the diff results to the same file incrementally using the ">>" redirction. Here is a sample on one file where I show you a few selected lines:
:~/OST-1$ svn > path/to/change-list-[date].txt
Index: howto/HowTo-template.html
========================================================================
=== howto/HowTo-template.html (revision 1)
+++ howto/HowTo-template.html (working copy)
@@ -4,13 +4,13 @@
<head>
<BASE HREF="http://www.opensourcetoday.org/">
- <title>Open Source Today - (Page Description)</title>
- <meta name="description" content="How To: Coding HTML & CSS Files by Hand ..." />
+ <title>Title Matches One Below</title>
+ <meta name="description" content="Another in the series: [...]
...
In these few short lines we see a remarkablely detailed set of changes has been shown with great clarity. There is no reason to further belabor the obvious. We are now getting very close to a commit stage. Next time we will be describing other additinal changes to the working copy. Moreover, the update command will be discussed, because it is of importance for those having other users with commit rights. The update can warn when a commit is in danger of be aborted; it also could provide a quick workaround. In any case, I will talk to you again in a couple of weeks.
Another in the Series
How To: Coding html and css files by hand. This time it is the use of common commands that have our attention, however, more specificly tied to the Subversion implementation. We learned from the status command the state of the working copy differences from its base in the repository. Moreover, we learned we must inform the source control system of additions and deletions we intend to take effect. Finally we looked at the differences in detail, line by line between the repository copy and our projected changes, additions and deletions. We are nearly ready to commit our working copy to make it the current version.
Corrections, suggested extension or comments write: How-To-Guy. If the mailto does not work, use this: hcohen[-At-]bst-softwaredevs.com.
© Herschel Cohen, All Rights Reserved
Return to Home or Tools Page
____________________________________________________________________
* Originally published on the Open Source Today site August 28, 2007. Content may have been altered prior to being moved onto Web Site Developers.