5.4. Getting Information about the RepositorySubversion has a number of different commands that allow you to query the repository and working copy for a wealth of information about their current states, as well as their history. As your development in a working copy progresses, these commands will become invaluable tools, letting you quickly find out things like "what files have I changed since the last commit?" or "which branch of this directory am I currently working on?" 5.4.1. Getting Information on the Current StateThe current state of the repository is easily queried with the svn status command, which outputs the current state of all files in your working copy that have been in some way modified from their pristine repository state.
The output for svn status consists of a list of files, one per line. By default, each line is made up of five columns of status information, followed by a filename. Each of the five columns uses single character symbols to convey the current status of the file. This is shown in Table 5.1.
Normally, svn status doesn't contact the repository. Instead, it determines which files have been modified by comparing them with pristine copies of the files, which Subversion keeps in the working copy's .svn directory. Sometimes, though, you are interested in seeing which files have also changed in the repository (and thus will be merged at the next svn update). To get this information out of Subversion, you need to run svn status with the --show-updates (-u) option.
The --show-updates option tells Subversion to output three pieces of extra information. The first is an * in the eighth column of output of each file that has been modified in the repository. Additionally, Subversoon will output the current revision of each file in the repository, as well as the HEAD revision of the repository, which the comparison is being made against.
If you want even more information, you can run svn status in verbose mode, using the --verbose (-v) option. In this mode, the status command will output all files, not just ones that have been modified (ignored files will still be ignored). Additionally, it will show the last revision in which each file was committed and who made the commit, as well as the current revision in the working copy, in the following order: current revision, last committed, last committed by.
If you would like to output all files, including those that have been ignored in the configuration files or the svn:ignore property, you can tell svn status to disregard ignores with --no-ignore. Getting Detailed File InfoSometimes you need detailed information about a particular file or directory. In this case, the command you want to use is svn info. The info command gives you a dump of all the information that Subversion has stored about a file or directory in the working copy.
The first few lines of the info command's output identify the file that we're dealing with. The Path entry shows the location of the file relative to the base of the working copy, whereas the Name entry shows just the basename of the file. URL, on the other hand, shows the URL of the file in the repository. After the identifiers, the next three items show the current state of the file in the working copy. The Revision enTRy shows the current revision of the file in the working copy, and the Node Kind enTRy indicates whether the entity being examined is a file or directory. Schedule shows whether the file is scheduled for any action on the next commit. An entry of normal (as in the preceding example) indicates that no specific action is scheduled. Next, some information about the file's history is given. The Last Changed Author entry gives the username of the last person to commit a change for the file, and of course the Last Changed Rev and Last Changed Date give the revision number and date of the last commit. Additionally, there are entries that tell you when the files contents (Text) were last updated, and when the file's properties were last updated in the current working copy. The final piece of information shown is a checksum. This is an MD5 sum of the pristine state of the file. This can be used to verify that the download from the repository wasn't corrupted, or to see if a file has changed in the working copy (of course, svn status is a much easier way to find that out). Often you only want a particular piece of information about a file, not the entire info data dump. The svn info command doesn't have any way to explicitly specify a particular piece of data, but it is easy enough to get that information by combining svn info with the UNIX command grep. All you have to do is use a pipe (|) to pass the output of svn info to grep and search for a string that begins with the property name that you're looking for (the ^ before Checksum tells grep to only find lines that begin with the word "Checksum").
By default, svn info is a non-recursive command. If you prefer that it recurse into directories, you can use the --recursive (-R) option. Of course, with multiple files it is even more likely that you will want to grep for just a single item in the output. However, if you just grab a single line, the output will be nearly useless, because in many cases you will have no idea which file each line is referring to. The easiest way to get useful, but not excessive, output (in this case) is to use the grep command to search for both the item of interest and either the Name or Path enTRies. That way, the name of each file is output, followed by the data entries you are interested in. For example, the following command finds the last changed date for every file in trunk.
Examining File ChangesAfter you get in the habit of using it regularly, the svn diff command will easily become one of your most used and most trusted tools in the Subversion toolbox. The basic function of svn diff is to output the differences between two revisions, showing additions and deletions inline with each other. By default, svn diff shows the differences between a file in your working copy and the pristine version of the current revision of that file. So, for example, if you have made changes to the file rabbit.c in your working copy, the diff command will show you exactly what those changes were.
The svn diff command doesn't stop at showing local modifications, though. By using the --revision (-r) option, you can make svn diff output the differences between arbitrary revisions of files. All you need to do is pass the --revision option with two revision numbers separated by a colon. The command then returns the differences between the first revision and the second revision.
You can even get svn diff to give you the differences between two completely different files, from two completely different revisions. To do so, first you give svn diff two different paths to files in your working copy or URLs to a repository. Then, if you want to specify the revisions for each file, you enter a --revision REV1:REV2, just as with a single file.
There is also another subtly different method that you can use for identifying which revision of a file to use, which is the peg revision method. Say, for example, that in revision 12 you had deleted a file named cat.html. Then, later, you renamed the file kitty.html to cat.html. If you do a diff on cat.html and compare revisions 10 and 32 using -r 10:32, Subversion will follow the history of the current cat.html file to compare it at the given revisions (which, at revision 10 was the file kitty.html). If you really want to compare the file cat.html that existed at revision 10 with the current cat.html, you need a way to specifically tell Subversion. This is done by appending the revision numbers after each filename with an @, instead of using the --revision option.
5.4.2. Getting the Repository's HistorySubversion provides a couple of commands for examining the history of a file or directory in the repository. Checking the LogsYou can easily see the entire log history of a file (or collection of files) by using the svn log command. When svn log is run with no options, it outputs the logs for the current directory, which includes the change histories for all of the files that are contained in the directory.
To specify individual files and directories that you would like the history for, you can list files on the command line that svn log should examine. These can either be a list of files in your working copy or a URL (which may be followed by a list of files relative to the URL to be used instead of the base URL).
Subversion shows each log entry, in descending revision order, for every file involved. All of the log entries for the different files are mixed into a single listing, and each log is shown only once, even if it applies to multiple files. By default, svn log doesn't give a breakdown showing which files each log applies to, but if you pass the --verbose (-v) option it will show that information.
The default behavior of svn log is to output the logs for all of the revisions from the given file's BASE revision back to revision number one (or, in the case of a URL, from the repository HEAD back to revision one). If you don't want that much information, you can restrict the revisions that are looked at by passing the --revision (-r) option to svn log, with a range of revisions in the form REV1:REV2 (you can also give just a single revision if that's all you want).
There is one quirk that you should be aware of regarding how svn log works. Its default behavior, if no URL or path is given, is to show the log for . (i.e., the current working copy directory). When the files in a directory are committed, though, the BASE revision of the directory is not updated. So, if you check out a directory at revision 2859 and then perform three commits of changes to files inside the directory, the directory will still be at revision 2859, even though some of its contents are at later revisions. If you then perform an svn log in the directory with no path, the BASE will be taken from the directory (2859), and none of the changes that were committed will be shown (which is probably not what you really wanted). To get a complete log output, with the BASE revision of the most recently committed file in your directory, a better way to run svn log is with a wildcard, instead of an empty path.
Who's to Blame?Another useful tool for examining a file's history is the svn blame command. The blame command causes Subversion to output an entire file, with information about which user committed each line, and what revision that commit occurred in.
You should be a little careful when trusting the output from svn blame, though. The blame entry for a line shows the last revision where any change was made, including whitespace. So, if a developer adjusts the spacing on a line, and then commits, that developer will be shown as the author, even though someone else may have actually made the last substantive modification. Examining Files in the RepositoryOften, you will find yourself wanting to know what files are in a particular directory in the repository. One option, of course, is to check out a working copy of that directory, but if all you want to know is the contents of the directory, checking out the whole thing wastes time and bandwidth, and is just generally an all-around clunky way of dealing with the problem. Fortunately, Subversion comes to your rescue with the svn list command. When you run svn list, it contacts the repository and downloads just a list of the files in the given directory, which are then output to the terminal. The directory to list needs to be supplied as a URL to a directory or file in a repository, or as a path to a directory in a working copy (in which case Subversion will use that file's associated URL to contact the repository). If no directory is given, svn list uses the current working copy directory.
The default behavior of svn list is to non-recursively display only the files that are in the HEAD revision of the given directory. If you would rather see a different revision, you can specify one with the --revision option, in which case Subversion will list the files that existed in that particular version. If you would like to see a recursive tree of the files in the given directory, you can request that with the --recursive option.
If you need more information than just the names of the files in a directory, you can use the --verbose option. In verbose mode, svn list will show (in addition to each file's name) the last revision the files were committed in, the user who made that commit, the date of the commit, and the size of the file, in bytes.
Getting a Single FileSometimes, you need to look at just one single file from the repository. Unfortunately, svn checkout doesn't allow you to specify just a single file, only directories. Getting single files is where the svn cat command comes in handy. When run, svn cat contacts the repository and downloads just a single file, which it outputs to the terminal. In many cases, you will then want to redirect (using a >) svn cat's output into a file.
|
Thursday, November 12, 2009
Section 5.4. Getting Information about the Repository
Subscribe to:
Post Comments (Atom)
No comments:
Post a Comment