Using Ruby SVN bindings to get file status

Jim Morris — Mon, 04 Sep 2006 11:51:35 -0700

If you Google around for information or even some documentation on the ruby SVN bindings you will find plenty of comments that it simply is not documented, so when I wanted to add an SVN status check to a UI I was working on (a project browser window for Rails), I had to "Use the source Luke". However given the bindings are actually mostly automatically generated by SWIG, and the actual details are hidden in a goo of swig generated c code, even that was a challenge.

Eventually I realized that the API was almost identical to the c level subversion API, not surprisingly, and for the most part it works the way you would expect. However I could not find any examples of the client status call, so here it is for anyone else struggling with this issue.

require "svn/core"
require "svn/client"
require "svn/wc"
require "svn/repos"

# define Consts for all the numeric status values
NONE = 1
UNVERSIONED = 2
NORMAL = 3
ADDED = 4
MISSING = 5
DELETED = 6
REPLACED = 7
MODIFIED = 8
MERGED = 9
CONFLICTED = 10
IGNORED = 11
OBSTRUCTED = 12
EXTERNAL = 13
INCOMPLETE = 14
# I added these so I can amalgamate repo and local status
UPDATED = 15
MODIFIED_NEWER = 16
NEWFILE = 17

$modes= { # Map status to English
    NONE => "None",
    UNVERSIONED => "unversioned",
    NORMAL => "normal",
    ADDED => "file added",
    MISSING => "missing",
    DELETED => "file removed",
    REPLACED => "deleted and then re-added",
    MODIFIED => "modified",
    MERGED => "received repos mods",
    CONFLICTED => "file modified and in conflict",
    IGNORED => "ignored",
    OBSTRUCTED =>  "unversioned resource is in the way of the versioned resource",
    EXTERNAL => "unversioned path populated by an svn:external property",
    INCOMPLETE => "directory doesn't contain a complete entries list",
    UPDATED => "newer version in repository",
    MODIFIED_NEWER => "modified and newer version in repository",
    NEWFILE => "new file in repository",
    nil => "Unknown status"
}

# this amalgamates the most common status between local and repository
def compute_status(status)
  # if modified in repo and localy
  return MODIFIED_NEWER if status.repos_text_status == MODIFIED && status.text_status != NORMAL
  # if added in repo and does not exist locally
  return NEWFILE if status.repos_text_status == ADDED && status.text_status == NONE
  # if repo is none then use local status
  return status.text_status if status.text_status != NORMAL
  # if normal locally but changed in repo
  return UPDATED if status.repos_text_status == MODIFIED
  # otherwise it must be normal
  NORMAL
end

ctx = Svn::Client::Context.new()

rev = ctx.status("/home/user/project/myproject", "HEAD", true, true) do |path, status|
  astat= compute_status(status)
  puts "#{path}: #{status.text_status},#{status.repos_text_status} = #{$modes[astat]}"

  unless status.entry.nil?
    puts(".....name: #{status.entry.name}")
    puts(".....url: #{status.entry.url}")
    puts(".....repos: #{status.entry.repos }")
    puts(".....revision: #{status.entry.revision}")
    puts(".....kind: #{status.entry.kind}")
    puts(".....schedule: #{status.entry.schedule}")
    puts(".....deleted: #{status.entry.deleted}")
    puts(".....absent: #{status.entry.absent}")
    puts(".....incomplete: #{status.entry.incomplete}")
    puts(".....cmt_date: #{status.entry.cmt_date}")
    puts(".....cmt_rev: #{status.entry.cmt_rev}")
    puts(".....cmt_author: #{status.entry.cmt_author}")
    puts(".....prop_time: #{status.entry.prop_time}")
    puts(".....text_time: #{status.entry.text_time}")
  end
end

This is a sample, it shows how to setup the client context, call the status call, and parse the results. I also added some sugar by defining the numeric status codes and adding a hash to translate them to english. I also compute an amalgamated status code from the local status and status in the repository, to get the extra status codes I added above.

The status parameter returned by the status() call turns out to be a standard svn status structure, containing various fields, the most interesting one as far as status is concerned are text_status and repos_text_status fields which are numeric fields which specifies the SVN status of the file locally and in the repository, I have created in the example above a bunch of constants to define each of the states, and a hash to turn them into english.

Note the compute_status() method which looks at both the local status and repository status to see what the relative state of any file is wrt the repository.

The other interesting field is the entry field, which contains bunch of data as shown above, and in the structure definition below.

There are more parameters that can be passed to the status call, but the last two I show should be set to true, as that allows recursion into sub directories and shows all files, by default recursion is true but all_files is false which only show files not under svn control.

The developers have made some attempt to make this relatively easy to use, you can forget about the apr pools and stuff, and the second parameter is usually a structure that tells it the version or revision to search for, this has been simplified so you can pass in a string describing the revision ("HEAD", "TAIL", etc) or a number denoting the revision number.

The status and entry structures have also had the types converted into convenient ruby types, but for reference I show the c struct definitions from the various svn header files...

Here is the full status structure from svn_wc.h

typedef struct svn_wc_status2_t
{
  /** Can be @c NULL if not under version control. */
  svn_wc_entry_t *entry;

  /** The status of the entries text. */
  enum svn_wc_status_kind text_status;

  /** The status of the entries properties. */
  enum svn_wc_status_kind prop_status;

  /** a directory can be 'locked' if a working copy update was interrupted. */
  svn_boolean_t locked;

  /** a file or directory can be 'copied' if it's scheduled for
   * addition-with-history (or part of a subtree that is scheduled as such.).
   */
  svn_boolean_t copied;

  /** a file or directory can be 'switched' if the switch command has been
   * used.
   */
  svn_boolean_t switched;

  /** The entry's text status in the repository. */
  enum svn_wc_status_kind repos_text_status;

  /** The entry's property status in the repository. */
  enum svn_wc_status_kind repos_prop_status;

  /** The entry's lock in the repository, if any. */
  svn_lock_t *repos_lock;

}

and the entry structure

typedef struct svn_wc_entry_t
{
  /* IMPORTANT: If you extend this structure, check svn_wc_entry_dup() to see
     if you need to extend that as well. */

  /* General Attributes */

  /** entry's name */
  const char *name;

  /** base revision */
  svn_revnum_t revision;

  /** url in repository */
  const char *url;

  /** canonical repository URL or NULL if not known */
  const char *repos;

  /** repository uuid */
  const char *uuid;

  /** node kind (file, dir, ...) */
  svn_node_kind_t kind;

  /* State information */

  /** scheduling (add, delete, replace ...) */
  svn_wc_schedule_t schedule;

  /** in a copied state */
  svn_boolean_t copied;
  /** deleted, but parent rev lags behind */
  svn_boolean_t deleted;

  /** absent -- we know an entry of this name exists, but that's all
      (usually this happens because of authz restrictions)  */
  svn_boolean_t absent;

  /** for THIS_DIR entry, implies whole entries file is incomplete */
  svn_boolean_t incomplete;

  /** copyfrom location */
  const char *copyfrom_url;

  /** copyfrom revision */
  svn_revnum_t copyfrom_rev;

  /** old version of conflicted file */
  const char *conflict_old;

  /** new version of conflicted file */
  const char *conflict_new;

  /** working version of conflicted file */
  const char *conflict_wrk;

  /** property reject file */
  const char *prejfile;

  /** last up-to-date time for text contents (0 means no information available)
   */
  apr_time_t text_time;

  /** last up-to-date time for properties (0 means no information available) */
  apr_time_t prop_time;

  /** base64-encoded checksum for the untranslated text base file,
   * can be @c NULL for backwards compatibility.
   */
  const char *checksum;

  /* "Entry props" */

  /** last revision this was changed */
  svn_revnum_t cmt_rev;

  /** last date this was changed */
  apr_time_t cmt_date;

  /** last commit author of this item */
  const char *cmt_author;

  /** lock token or NULL if path not locked in this WC
   * @since New in 1.2.
   */
  const char *lock_token;
  /** lock owner, or NULL if not locked in this WC
   * @since New in 1.2.
   */
  const char *lock_owner;
  /** lock comment or NULL if not locked in this WC or no comment
   * @since New in 1.2.
   */
  const char *lock_comment;
  /** Lock creation date or 0 if not locked in this WC
   * @since New in 1.2.
   */
  apr_time_t lock_creation_date;

  /* IMPORTANT: If you extend this structure, check svn_wc_entry_dup() to see
     if you need to extend that as well. */
} svn_wc_entry_t;

For the most part you can simply reference the fields in the structure and get a relatively understandable result.

The status call is defined in ruby as this

def status(path, rev=nil, recurse=true, get_all=false,
           update=true, no_ignore=false,
           ignore_externals=false, &status_func)

The first parameter is the path on the local file system to get the status of, the second is the revision to get, something like "HEAD", or 2345 can be passed in, the next parameter is whether to recurse into subdirectories, the next tells it to return the status of all files if set to true, default of false and only returns "interesting files" ie local mods and/or out-of-date or not versioned. Update is set to true it will contact the repository to get more information wrt to the version specified in the first parameter (which is ignored otherwise). I couldn't find any documentation in the c stuff about the no_ignore parameter, but the ignore_externals tells it to return status on externals or not. See the header file svn_client.h and the call svn_client_status2 for more documentation.

ruby svn

"Using Ruby SVN bindings to get file status" by Tim Coulter

Mon, 05 Mar 2007 22:48:27 -0800

To anyone interested:

A lot of people seem to be having trouble finding documentation for the Ruby Subversion bindings. I've found a couple things out, and blogged about it here:

http://www.oneofthewolves.com/2007/03/06/ruby-subversion-bindings-finally-some-documentation/

"Using Ruby SVN bindings to get file status" by wolfmanjm

Fri, 22 Dec 2006 13:54:35 -0800

you can ask questions, but there is little to no documentation. Use the SVN c bindings docs as a guide, there is almost a 1:1 mapping from c to ruby.

"Using Ruby SVN bindings to get file status" by Toni Schilling

Fri, 22 Dec 2006 08:01:40 -0800

Great! This is the 1st (first) example for ruby+svn I've found. I experienced exactly what you write in your intro. I'm new in Ruby, but I use SVN, C++, cygwin ... so may be I'll have some questions. May I? E.g.: can you point me to some docu/howto/sample for the svn-api ? Not the just the source code but some thing like an overview/what-is-what ... Thank you and Merry Christmas Toni

Wolfmans Howlings: Using Ruby SVN bindings to get file status

Using Ruby SVN bindings to get file status

"Using Ruby SVN bindings to get file status" by Tim Coulter

"Using Ruby SVN bindings to get file status" by wolfmanjm

"Using Ruby SVN bindings to get file status" by Toni Schilling