svnbranch 0.2.0

data/lib/svnbranch.rb

@@ -0,0 +1,56 @@
+# $Id$
+
+# Equivalent to a header guard in C/C++
+# Used to prevent the class/module from being loaded more than once
+unless defined? Svnbranch
+
+module Svnbranch
+
+  # :stopdoc:
+  VERSION = '0.2.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, *args)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, *args)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Svnbranch
+
+Svnbranch.require_all_libs_relative_to __FILE__
+
+end  # unless defined?
+
+# EOF

data/man1/Makefile

@@ -0,0 +1,19 @@
+all:	text ps html
+
+text:
+	man ./svnbranch.1
+#	nroff -man svnbranch.1 | less
+
+ps:	svnbranch.ps
+
+html:	svnbranch.html
+
+clean:	
+	rm svnbranch.ps svnbranch.html
+
+svnbranch.ps: svnbranch.1
+	groff -man svnbranch.1 > svnbranch.ps
+	open svnbranch.ps
+
+svnbranch.html: svnbranch.1
+	groff -man -Thtml svnbranch.1 > svnbranch.html

data/man1/svnbranch.1

@@ -0,0 +1,526 @@
+.de EX
+.nf
+.in +0.5i
+\fB\\$1\fP\\$2
+.in -0.5i
+.ad
+.fi
+..
+.de CW
+\&\f(CW\\$1\fP\\$2
+..
+.TH SVNBRANCH 1 "Karrick S. McDermott"
+.
+.SH NAME
+svnbranch \- Subversion branching (made easy)
+.SH SYNOPSIS
+.BR svnbranch " [ " \-h " | " \-\-help " | " help " ] "
+.br
+.BR svnbranch " [ " \-d " | " \-f " | " \-s " | " \-v " | " \-q " ] "
+\fBcreate\fP \fInew-branch\fP [ \fIsub-branch\fP ]
+.br
+.BR svnbranch " [ " \-d " | " \-f " | " \-v " | " \-q " ] "
+\fBclose
+.br
+.BR svnbranch " [ " \-d " | " \-f " | " \-v " | " \-q " ] "
+\fBmerge\fP \fImerge-branch\fP [ \fIsub-branch\fP ]
+.br
+.BR svnbranch " [ " \-d " | " \-f " | " \-v " | " \-q " ] "
+\fBdelete\fP \fIdoomed-branch\fP [ \fIsub-branch\fP ]
+.br
+.BR svnbranch " [ " \-d " | " \-f " | " \-v " | " \-q " ] "
+\fBswitch\fP \fIswitch-branch\fP [ \fIsub-branch\fP ]
+.br
+.SH DESCRIPTION
+.PP
+.CW Svnbranch
+is a program that can assist with managing Subversion branches.
+.PP
+.CW Svnbranch
+operates in five basic modes:
+.BR create ", " close ", "
+.BR merge ", " delete ", and " switch .
+.
+Most of the time, you will use the
+.BR create ", " close ", and "
+.B merge
+features to work with Subversion repositories.
+.
+The \fBswitch\fP mode is used to change the current Subversion
+\fIworking directory\fP to use a different existing branch from the Subversion
+server.
+.
+The \fBdelete\fP mode is considered advanced usage, and a detailed
+understanding of the warnings below is recommended prior to use.
+.
+.SH OPTIONS
+.TP 5
+.B \-d
+Display debugging information.
+.I This can get fairly lengthly and quickly obscures overall
+.I program progress.
+.
+.TP 5
+.B \-f
+Forces
+.CW Svnbranch
+to perform the next action, even if an automatic fail-safe protection
+feature would prevent the action from taking place.
+.
+This can be used during a \fBcreate\fP operation, to create a new branch
+regardless of whether there are uncommitted files in your repository.
+.
+It can also be used dureing a \fBclose\fP operation, to delete the
+\fI...\fP/\fBtags\fP/\fItest-branch\fP\fB-POST\fP directory from the
+Subversion server and create a new one.
+.
+.TP 5
+.BR "\-h" " | " "\-\-help"
+Display 
+.CW Svnbranch's " man page using the system \fBman\fP utilitiy."
+.
+.I This is necessary because the
+.B gem
+.I utility does not install man pages.
+.
+.TP 5
+.B \-q
+Causes
+.CW Svnbranch
+to refrain from displaying any information unless there is an error
+or warning.
+.
+.I "Note: If there"
+.B is
+.I "an error, a full back-trace will"
+.I "be displayed for diagnostic purposes."
+.
+.TP 5
+.B \-s
+Used with the \fBcreate\fP mode.
+.
+Causes
+.CW Svnbranch
+to re-use the Subversion \fIworking directory\fP for the new branch,
+instead of recursively copying the directory to a new location.
+.
+This is most useful when working with an extremely large repository,
+but it limits your flexibility to quickly switch from one branch to another
+once changes have been made in the branch \fIworking directory\fP.
+.
+.TP 5
+.B \-v
+Display verbose information concerning the operations that
+.CW Svnbranch
+is performing.
+.
+.I This is the default level of verbosity.
+.
+.SH MODES
+.TP 5
+.B create 
+Used to create a new branch on the Subversion repository derived from the
+branch\(emor trunk\(emof the current Subversion \fIworking directory\fP.
+.
+.TP 5
+.B close
+Used to mark completion of changes on the present branch.
+.
+.TP 5
+.B merge
+Used to merge changes from a previously closed Subverion branch into the
+current \fIworking directory\fP.
+.
+It is highly recommended that after merging, that you re-compile, and
+test your project before re-committing changes back to the Subversion
+server.
+.
+.B It is not safe to re-merge a previously merged branch into the same
+.B working directory more than once.
+.
+.TP 5
+.B delete
+Used to remove any and all trace of the specified branch from the Subversion
+repository without any further prompting or warnings.
+.
+This amounts to the three directories on the Subversion server at
+\fBbranches\fP/\fIdoomed-branch\fP,
+\fBtags\fP/\fIdoomed-branch\fP\fB-PRE\fP, and
+\fBtags\fP/\fIdoomed-branch\fP\fB-POST\fP.
+.
+.TP 5
+.B help
+Synonym for \fB--help\fP.
+.
+.TP 5
+.B switch
+Used to switch the current \fIworking directory\fP to a different existing 
+branch on the Subversion server.
+.
+.SH SAFETY
+.CW Svnbranch
+performs systematic tests on the status of both your \fIworking directory\fP
+and the Subversion server to maintain a logically consistent state in both
+places.
+.
+If
+.CW Svnbranch
+detects an unusual situation, it will display an error message,
+.IR "(see DIAGNOSTIS below)" ,
+then aborts the process prior to making any changes.
+.
+.SH EXAMPLE WORK-FLOW
+.PP
+For the purposes of the following description, the phrase
+.I "working directory"
+refers to your current working directory that has been checked out
+from a repository on the Subversion server:
+.
+.sp
+.EX "svn co https://www.example.com/svn/myproject/trunk ~/myproject/trunk"
+.sp
+.CW Svnbranch
+is invoked from within the \fIworking directory\fP, corresponding to either a
+repository trunk or a branch.
+.
+Note, there is no directory name requirement for the \fIworking
+directory\fP name, whether you are working from the trunk or a branch.
+.
+The starting directory could easily have been
+.CW "~/myproject",
+and the process would have worked as expected.
+.sp
+.EX "cd ~/myproject/trunk"
+.sp
+When using the \fBcreate\fP mode,
+.CW Svnbranch
+will create a branch on the Subversion server, and create a tag on the 
+Subversion server to mark the commencement of work on the new branch.
+.
+Finally, it will copy the files on your local system to allow you to work
+in the newly created branch.
+.sp
+.EX "svnbranch create BUG-1234"
+.sp
+Change your \fIworking directory\fP to the newly created directory on your 
+local system:
+.sp
+.EX "cd ../BUG-1234"
+.EX "..."
+.sp
+Edit, compile, \fItest\fP, and repeat until the bug is eliminated.
+.
+After testing the changes, commit them back to the repository from
+the \fIworking directory\fP:
+.sp
+.EX "svn commit -m 'removed memory leak by calling free() in foo().'"
+.sp
+Then tag the end of the branch by using the \fBclose\fP mode of operation:
+.sp
+.EX "svnbranch close"
+.sp
+When you desire to merge the changes from a branch back into either
+the trunk or a different branch, simply change your
+\fIworking directory\fP to the desired branch and have
+.CW Svnbranch
+pull the branch changes from the Subversion server:
+.sp
+.EX "cd ../trunk"
+.EX "svnbranch merge BUG-1234"
+.EX "..."
+.sp
+.BR Note :
+The merge of the changes from the specified branch back to the Subversion
+repository has not happened yet.
+.
+.sp
+You should compile and test the merged changes in this
+\fIworking directory\fP to ensure the changes are effective in this
+directory as well.
+.
+.I This is even more important in a multi-user development environment.
+.sp
+After testing reveals no bugs, Subversion is used to merge the revised
+source code back into the source code maintained by the Subversion
+server:
+.sp
+.EX "svn commit -m 'Merged bug fix from [BUG-1234] branch into [trunk].'"
+.sp
+You can merge the changes into various branches.
+.
+For example, here the changes are merged from the same bug fix to a maintenance
+branch:
+.sp
+.EX "cd ../2.1-maint"
+.EX "svnbranch merge BUG-1234"
+.EX "...(testing)..."
+.EX "svn commit -m 'Merged bug fix from [BUG-1234] branch into [2.1-maint].'"
+.sp
+.SH EXAMPLE WORK-FLOW (Using Switch Mode)
+.PP
+When working with extremely large repositories, the normal \fBcreate\fP mode
+above can take quite a long time to copy files on your local system.
+.
+In this case, you can \fBcreate\fP a new branch, instructing
+.CW Svnbranch
+to re-use the current \fIworking directory\fP instead of copying the
+directory hierarchy:
+.
+.sp
+.EX "svnbranch -s create hash-test"
+.EX "..."
+.sp
+At the conclusion of the above command, a new branch has been created on 
+the Subversion server, and your \fIworking directory\fP has been switched 
+to that new branch.
+.
+There is no need to change directories to begin work, because
+.CW Svnbranch
+did not create a new directory.
+.
+After changes are complete, tested, and committed, the branch may be
+closed as normal:
+.sp
+.EX "svn commit -m 'improved hash method working and tested'"
+.EX "svnbranch close"
+.sp
+Then switch back to your previous branch using the \fBswitch\fP
+mode and pull the changes from the branch into your \fIworking directory\fP:
+.
+.sp
+.EX "svnbranch switch trunk"
+.EX "svnbranch merge hash-test"
+.EX "..."
+.sp
+Once again, you will have to compile and test your program.
+.
+After testing is complete, commit your changes to the Subversion
+server as you normally would:
+.sp
+.EX "svn ci -m 'Merged [hash-test] into [trunk].'"
+.SH SUB-BRANCHES
+.CW Svnbranch
+supports using nested hierarchical directories on the Subversion
+server to organize your repository.  For instance, your work environment
+may require you to place all of your experimental branches in a
+directory nested below your login name:
+.sp
+.EX "svnbranch create pat/hash-test"
+.sp
+Similarly, some organizations require bug-fix branches in their own
+sub-directory of the repository server:
+.sp
+.EX "svnbranch create bug-fixes/BUG-1234"
+.PP
+.BR Note :
+Multiple levels of sub-branches may be specified, separated by the slash,
+\fB/\fP, character:
+.sp
+.EX "svnbranch create pat/experimental/hash-test"
+.sp
+This creates a branch at
+\fI...\fP/\fBmyproject\fP/\fBbranches\fP/\fBpat\fP/\fBexperimental\fP/\fBhash-test\fP
+on the Subversion server.
+.
+.SH NOTES
+.IP "Outstanding changes"
+.CW Svnbranch
+prevents you from creating, closing, merging, or switching a branch unless you have no 
+outstanding file edits or changes to be checked in from your
+.IR "working directory" .
+.
+.IP "Subversion repository requirements"
+To use
+.CW Svnbranch
+effectively, your Subversion repository should have a
+.BR trunk ", " branches ", and a " tags " directory."
+.
+.CW Svnbranch
+will attempt to create a
+.BR branches " and a " tags
+directory as sibling directories to the \fBtrunk\fP directory if those
+are missing on the server.
+.
+.CW Svnbranch
+will not create a \fBtrunk\fP directory if one is not present.
+.
+.I Nor is a trunk directory strictly required.
+.I Your responsibilities may require you to integrate bug-fixes into
+.I various maintenance branches at your organization.
+.I In this circumstance, you would not even need to have the \fBtrunk\fP checked
+.I out.
+.I Simply check out a maintenance branch, and integrate changes:
+.sp
+.EX "svn co https://www.example.com/svn/myproject/branches/2.1-maint ~/work"
+.EX "cd ~/work"
+.EX "svnbranch merge BUG-1234"
+.EX "...(test)..."
+.EX "svn ci -m 'Merged bug-fix [BUG-1234] into maintenance branch [2.1-maint].'"
+.sp
+.IP "Creating\(em\fBRsync\fP"
+For efficiency purposes,
+.CW Svnbranch
+attempts to use the \fBRsync\fP utility to copy the files on the local
+system when creating a new branch.
+.
+If
+.CW Svnbranch
+cannot find the \fBRsync\fP utility on the system,
+.CW Svnbranch
+will use standard file-system API calls, via \fBRuby\fP's
+.B FileUtils
+library, to create the \fIworking directory\fP for the new 
+branch, clobbering over any directory already present with the same name.
+.
+.IP "Closing"
+Do not use any branch or sub-branch identifiers for the \fBclose\fP
+mode of operation.
+.
+.CW Svnbranch
+will learn these from inspecting your current \fIworking directory\fP.
+.
+Any attempts to specify a branch or sub-branch name for a \fBclose\fP
+operation will result in an error message being displayed.
+.
+No changes will be made to the Subversion server repositories in this
+event.
+.
+.SH CAVEATS
+.IP "Creating"
+Results are not determined if you create a new branch from a directory
+that is not the root directory of a project.
+.
+.IP "Creating a branch of a \fIlarge repository\fP"
+For large Subversion repositories, creating a new branch can take a significant
+amount of time as the repository files are pulled from the Subversion server.
+.
+.CW Svnbranch
+mitigates this by splitting the operation into three steps, significantly 
+improving performance:
+.in +0.5i
+.sp
+First,
+.CW Svnbranch
+instructs the Subversion server to duplicate the repository remotely
+on the server, using minimal network bandwidth.
+.sp
+Second, instead of checking out the new branch over the network,
+.CW Svnbranch
+duplicates the \fIworking directory\fP locally.
+.
+.CW Svnbranch
+further improves performance by attempting to use the \fBRsync\fP utility
+on the local system to expedite the file copy process.
+.
+.I (See NOTES above.)
+.sp
+Third,
+.CW Svnbranch
+instructs the local system to change which remote repository is pointed to by
+the newly created \fIworking directory\fP.
+.
+.sp
+.in -0.5i
+For all but the largest of working directories, this process is relatively 
+fast.
+.
+However, during
+.CW Svnbranch
+development, a repository larger than 8 gigabytes was routinely used
+for testing.
+.
+The delay was noticeable\(emtaking approximately 10 minutes to complete.
+.
+.SH WARNING
+.IP "Deleteing a branch"
+Deleteing a branch is considered an advanced mode of operation for
+.IR Svnbranch ,
+and it should be done only with a detailed understanding of how
+.CW Svnbranch
+manages branches on the Subversion repository server.
+.
+.sp
+When 
+.CW Svnbranch
+creates a new branch, it creates a copy of the
+working branch in the \fBbranches\fP directory on the Subversion server.
+.
+Then creates a tag to mark the start of changes in this new branch in the
+\fBtags\fP directory.
+.
+Later, when someone \fBclose\fPs a branch, 
+.CW Svnbranch
+will create a new tag to mark the end of changes in the \fBtags\fP directory.
+.
+.sp
+If for some reason you desire to remove all traces of the specified
+branch from the Subversion repository, the \fBdelete\fP operation can be used
+to delete the relevant directories from the Subversion repository.
+.
+When invoked with the \fBdelete\fP mode, 
+.CW Svnbranch
+will remove any and all of these three directories from the Subversion
+repository without any further prompting or warnings.
+.
+.SH DIAGNOSTICS
+.PP
+.CW Svnbranch
+uses the \fBWatcher\fP Ruby gem,
+which provides a combined logging and condition-handling
+mechanism for Ruby programs.
+.
+As such, when an error or warning occurs,
+.CW Svnbranch
+will display all the previous log messages that had been masked by
+.BR Watcher .
+.
+.sp
+Although not usually needed, you may direct
+.CW Svnbranch
+to display more verbose status messages, by invoking it with
+the \fB\-d\fP command line option.
+.
+.SH BUGS
+.IP Merging
+It is not safe to re-merge a previously merged branch into the same
+working directory more than once.
+.
+.IP "Runtime Errors"
+.CW Svnbranch
+makes all practical attempts to ensure the Subversion server's
+repositories are left in a logically correct state in the event of a
+runtime error.
+.
+If
+.CW Svnbranch
+aborts a process in the middle of command due to an error or its
+process is stopped, the Subversion repository may be in an inconsistant state.
+.
+.sp
+For instance, say that the user hits Ctrl-C during a create process, after
+.CW Svnbranch
+has created
+\fI...\fP/\fBmyproject\fP/\fBbranches\fP/\fItest-branch\fP, but before
+it has created
+\fI...\fP/\fBmyproject\fP/\fBtags\fP/\fItest-branch\fP\fB-PRE\fP.
+.
+In this event, you may have to use the below command to clean up the repository
+on the Subversion server, then try again:
+.sp
+.EX "svnbranch delete \fItest-branch\fP"
+.sp
+.SH "SEE ALSO"
+.TP 5
+.BR svn (1)
+Subversion command line client tool
+.TP 5
+.BR svnadmin (1)
+Subversion repository administration tool
+.TP 5
+.BR rsync (1)
+A fast, versatile, remote (and local) file-copying tool
+.TP 5
+.B Watcher
+A gem for logging and condition-handling of Ruby programs.
+.SH AUTHOR
+Karrick S. McDermott

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# $Id$
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib svnbranch]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+# EOF

data/spec/svnbranch_spec.rb

@@ -0,0 +1,8 @@
+# $Id$
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Svnbranch do
+end
+
+# EOF

data/tasks/ann.rake

@@ -0,0 +1,81 @@
+# $Id$
+
+begin
+  require 'bones/smtp_tls'
+rescue LoadError
+  require 'net/smtp'
+end
+require 'time'
+
+namespace :ann do
+
+  # A prerequisites task that all other tasks depend upon
+  task :prereqs
+
+  file PROJ.ann.file do
+    ann = PROJ.ann
+    puts "Generating #{ann.file}"
+    File.open(ann.file,'w') do |fd|
+      fd.puts("#{PROJ.name} version #{PROJ.version}")
+      fd.puts("    by #{Array(PROJ.authors).first}") if PROJ.authors
+      fd.puts("    #{PROJ.url}") if PROJ.url.valid?
+      fd.puts("    (the \"#{PROJ.release_name}\" release)") if PROJ.release_name
+      fd.puts
+      fd.puts("== DESCRIPTION")
+      fd.puts
+      fd.puts(PROJ.description)
+      fd.puts
+      fd.puts(PROJ.changes.sub(%r/^.*$/, '== CHANGES'))
+      fd.puts
+      ann.paragraphs.each do |p|
+        fd.puts "== #{p.upcase}"
+        fd.puts
+        fd.puts paragraphs_of(PROJ.readme_file, p).join("\n\n")
+        fd.puts
+      end
+      fd.puts ann.text if ann.text
+    end
+  end
+
+  desc "Create an announcement file"
+  task :announcement => ['ann:prereqs', PROJ.ann.file]
+
+  desc "Send an email announcement"
+  task :email => ['ann:prereqs', PROJ.ann.file] do
+    ann = PROJ.ann
+    from = ann.email[:from] || PROJ.email
+    to   = Array(ann.email[:to])
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{from}\n"
+    rfc822msg << "To: #{to.join(',')}\n"
+    rfc822msg << "Subject: [ANN] #{PROJ.name} #{PROJ.version}"
+    rfc822msg << " (#{PROJ.release_name})" if PROJ.release_name
+    rfc822msg << "\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: "
+    rfc822msg << "<#{"%.8f" % Time.now.to_f}@#{ann.email[:domain]}>\n\n"
+    rfc822msg << File.read(ann.file)
+
+    params = [:server, :port, :domain, :acct, :passwd, :authtype].map do |key|
+      ann.email[key]
+    end
+
+    params[3] = PROJ.email if params[3].nil?
+
+    if params[4].nil?
+      STDOUT.write "Please enter your e-mail password (#{params[3]}): "
+      params[4] = STDIN.gets.chomp
+    end
+
+    ### send email
+    Net::SMTP.start(*params) {|smtp| smtp.sendmail(rfc822msg, from, to)}
+  end
+end  # namespace :ann
+
+desc 'Alias to ann:announcement'
+task :ann => 'ann:announcement'
+
+CLOBBER << PROJ.ann.file
+
+# EOF