svn_wc 0.0.1

data/ChangeLog

@@ -0,0 +1,2 @@
+version 0.0.1 
+* initial checkin

data/LICENSE

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/Manifest

@@ -0,0 +1,8 @@
+ChangeLog
+LICENSE
+Manifest
+README
+svn_wc_conf.yaml
+svn_wc.gemspec
+lib/svn_wc.rb
+test/svn_wc_test.rb

data/README.rdoc

@@ -0,0 +1,312 @@
+= SvnWc::RepoAccess
+
+Operate on the working copy of a (remote) Subversion (svn) repository.
+
+
+== VERSION:
+
+Version 0.0.1
+
+
+== SYNOPSIS:
+ruby code
+
+    require 'svn_wc'
+    
+    # assumes a previous initial checkout
+    svn_wc = SvnWc::RepoAccess.new
+    
+    svn_wc.set_conf 'svn_wc_conf.yaml'
+    
+    # checkout, needed first time only, 
+    # 'true',  force overwrite of working copy directory path
+    #svn_wc.do_checkout true
+    
+    file = Tempfile.new('test_', svn_wc.svn_repo_working_copy).path
+    begin
+      svn_wc.add file
+      puts "svn Added file: #{file}"
+      rev = svn_wc.commit file
+      raise 'commit failed' unless rev >= 1
+      puts "svn committed file: #{file}, revision #{rev}"
+      svn_wc.delete file
+      # commit our delete
+      rev = svn_wc.commit file
+      puts "svn deleted file: #{file}, revision #{rev}"
+      raise 'commit failed' unless rev >= 1
+    rescue SvnWc::RepoAccessError, Exception => e
+      raise e.message
+    end
+
+
+== DESCRIPTION:
+
+This library is designed to operate on a working copy (on the local file system) of a remote Subversion repository.
+
+Currently, it provides very basic svn functions (see FEATURES) driven programmatically.
+It uses the Subversion Ruby Bindings to utilize/expose their functionality in a simplified way.
+
+It does not do any sort of repository administration type operations, just working directory repository management.
+
+
+== FEATURES:
+
+* Programatic access to the following:
+
+* Current supported operations
+  - open
+  - checkout/co
+  - list/ls
+  - update/up
+  - commit/ci
+  - status/stat
+  - diff
+  - info
+  - add
+  - revert
+  - delete
+  - svn+ssh is our primary connection use case, however can connect to, and operate on a (local) file:/// URI as well
+
+
+== REQUIREMENTS:
+
+* Requires that the Subversion (SWIG) Ruby Bindings are installed. 
+    (which could be as easy as)
+    Linux
+    Redhat and Fedora: yum install subversion-ruby
+    Ubuntu and Debian: apt-get install libsvn-ruby
+    OS X
+    sudo port install subversion-rubybindings
+    Windows
+    unknown,...
+
+* Ruby 1.8.6 (not tested with previous, or later versions, should work anywhere the ruby bindings are installed)
+
+== INSTALL:
+
+This library is intended to be installed as a Gem. (hosted on gemcutter.org)
+ ($ gem source -a http://gemcutter.org - no longer needed)
+
+  $ gem install svn_wc
+
+
+== OVERVIEW:
+
+This library was written to be the back end for a web app GUI front end. (Currently in progress)
+
+This serverfault post describes what I was looking for and what I am trying to satisfy with the (Front End) Application:
+
+    "I want a web interface to manage a WORKING COPY of a repository (NOT the repository itself). 
+    There are lots of already made tools to manage the repository, but I also have not found a 
+    single one to manage a remote working copy.  I need a user-friendly interface to perform stuff like:
+    "svn status", "svn info", "svn commit", "svn update", "svn revert",
+    "svn add", "svn delete"  and "svn diff"... upon a WORKING COPY which resides
+    in a remote host.  (I'm not interested in the repository, I'm interested in the WORKING COPY
+    management.)
+    I don't want to do SSH login and perform these commands. I want to enable
+    not-advanced users to do some stuff in the hosted working copy, using a
+    web interface,...
+
+* {serverfault link}[http://serverfault.com/questions/52532/svn-web-interface/67788#67788]
+
+== USAGE:
+
+Provide the svn connection info upon initializaion. 
+(One can also provide the path to a conf file. See 'svn_wc_conf.yaml')
+
+ruby code
+    require 'svn_wc'
+
+    yconf = Hash.new
+    yconf['svn_user']              = 'test_user'
+    yconf['svn_pass']              = 'test_pass'
+    yconf['svn_repo_master']       = 'svn+ssh://www.example.com/svn_repository'
+    yconf['svn_repo_working_copy'] = '/opt/svn_repo'
+
+    # 'do_checkout' is only needed until the local repository exists. (i.e. usually first time run only)
+    # 'force' will plow over anything that may exist at the path.
+    # i.e. if you ask for a do_checkout without force and the local repo exists, the call will fail
+
+    svn = SvnWc::RepoAccess.new(YAML::dump(yconf), do_checkout=true, force=true)
+
+    puts svn.svn_repo_master       # 'svn+ssh://www.example.com/svn_repository'
+    puts svn.svn_user              # 'test_user'
+    puts svn.svn_pass              # 'test_pass'
+    puts svn.svn_repo_working_copy # '/opt/svn_repo'
+
+    info = svn.info                # another way
+    puts info[:root_url]           # 'svn+ssh://www.example.com/svn_repository'
+
+    file = Tempfile.new('tmp', svn.svn_repo_working_copy).path
+    begin
+      svn.info(file)
+    # SvnWc::RepoAccess' generic exeception class (the only one, raised for all exceptions)
+    rescue SvnWc::RepoAccessError => e
+      puts e.message.match(/is not under version control/)
+    end
+
+    svn.add file
+
+    puts svn.commit file               # returns the revision number of the commit
+
+    puts svn.status file               # ' ' empty string, file is current
+
+    File.open(file, 'a') {|f| f.write('adding this to file.')}
+
+    puts svn.status(file)[0][:status]  # 'M' (modified)
+    # or, whole repo, multiple entries
+    svn_wc.status.each do |entries|
+      puts "#{entries[:status]}\t#{entries[:path]}"
+    end
+
+    puts svn.info(file)[:rev]          # current revision of file
+    svn_wc.info(file).each_key do |entries|
+      puts entries[:rev]
+      puts entries[:last_changed_author]
+      puts entries[:last_changed_rev]
+    end
+
+    puts svn.diff(file)                # =~ 'adding this to file.'
+
+    svn.revert file
+    svn.commit file                    # -1 i.e commit failed, file is current
+
+    svn.delete file
+    svn.commit file                    # must commit our delete
+
+    (In general, the above operations also accept a list (array) in place of a single file)
+
+
+    See test/* for more examples.
+
+
+== DIAGNOSTICS
+
+* An exception such as 
+    SvnWc::RepoAccessError  => 
+    'Add Failed: /tmp/buildd/subversion-1.6.3dfsg/subversion/libsvn_wc/lock.c:572:
+    Svn::Error::WcNotDirectory: '/path/to/repository' is not a working copy (RuntimeError)'
+
+  means there is no working directory where you have specified there is one,
+  you need to do a 'do_checkout'
+  i.e.  svn = SvnWc::RepoAccess.new('conf.yaml', do_checkout=true, force=true)
+
+* All the exceptions received using this module should be SvnWc::RepoAccessError 
+  which produce a (hopefully helpful) message, which is usually just the underlying 
+  exception returned from the Ruby SWIG library
+
+
+== CONFIGURATION AND ENVIRONMENT:
+
+* In order to make use of this module, one must provide connection information for svn
+
+  One can provide this as a hash at Runtime, or as a configuration file:
+
+   # conf file (YAML)
+   $ cat svnwc_conf.yaml 
+   # svn connection info
+   #svn_repo_master       : file:///tmp/svnrepo
+   svn_repo_master        : svn+ssh://example.com/opt/svnrepo
+   svn_repo_working_copy  : /usr/local/svn/repo_root
+   svn_user               : svn_test_user
+   svn_pass               : svn_test_pass
+   svn_repo_config_path   : /opt/config
+
+   # conf info
+   yconf = Hash.new
+   yconf['svn_user']              = 'test_user'
+   yconf['svn_pass']              = 'test_pass'
+   yconf['svn_repo_master']       = 'svn+ssh://www.example.com/svn_repository'
+   yconf['svn_repo_working_copy'] = '/opt/svn_repo'
+
+   svn = SvnWc::RepoAccess.new YAML::dump(yconf)
+
+* This library should work anywhere that the 'subversion-rubybindings' are installed
+  (.*NIX systems,...)
+
+
+== DEPENDENCIES:
+
+  require 'yaml'
+  require 'pathname'
+  require 'find'
+  require 'svn/core'
+  require 'svn/client'
+  require 'svn/wc'
+  require 'svn/repos'
+  require 'svn/info'
+  require 'svn/error'
+
+
+== INCOMPATIBILITIES:
+
+none known of
+
+
+== BUGS AND LIMITATIONS:
+
+This library currently provides only very basic svn operations, more work is
+needed if more functionality is desired. i.e. propset/propget, specific
+revisions operations, etc
+
+
+== SUPPORT:
+
+ri 'svn_wc'
+
+* {svn_wc general page}[http://www.dwright.us/misc/svn_wc]
+
+
+== CHANGELOG:
+
+See the ChangeLog file for details.
+
+
+== LICENSE AND COPYRIGHT:
+
+Copyright 2009 David Wright (david_v_wright@yahoo.com), all rights reserved.
+
+
+SvnWc::RepoAccess 0.1.0 is released under the LGPL license.
+
+
+== AUTHOR:
+
+Author:: {David Wright}[http://www.dwright.us/] <david_v_wright@yahoo.com>
+
+
+=== KEYWORDS:
+
+* Ruby (SWIG) SVN bindings, ruby+svn, ruby, subversion, svn, rubysvn, Subversion extensions in Ruby 
+
+
+== ACKNOWLEDGEMENTS:
+
+*  Much of this code was guided from reading the {SVN Ruby Bindings unit tests}[https://svn.collab.net/repos/svn/trunk/subversion/bindings/swig/ruby/test/]
+
+* {Doxygen Docs}[http://svn.collab.net/svn-doxygen/search.php?query=svn_wc_entry]
+  Ruby          -> Svn::Wc::Entry 
+  Doxygen Docs  -> svn_wc_entry
+
+* The Doxyogen Modules {docs}[http://svn.collab.net/svn-doxygen/modules.html]
+
+* Tim Coulter did some work with the {Ruby bindings as well}[http://www.oneofthewolves.com/svn_repos/svn_repos.rb]
+
+* "Perl Best Practices" (Conway), module documentation guidelines.
+
+
+=== ERRATA:
+
+* There is no Ruby specific documentation on the Ruby Bindings SWIG library, there are the Doxygen docs only.
+
+* Explanation/Intention
+    My use case scenario is a svn working copy on the local file system
+    communicating with a remote SVN repository, as such, I can not make use of any
+    of the 'Svn::Fs' module functionality, which is unfortunate.  Mainly, I rely
+    on the 'Svn::wc' module.
+    
+    My aim was to make this work similarly to what I'm used to in the CLI
+    version, as far as commands and the responses to commands.
+    
+    Hopefully, this library, or at least some of the code is useful to someone.
+