#!/bin/sh
#
# =========================================================================
# Copyright 2004 Josh Glover <jmglov@jmglov.net>
#
# LICENCE:
#
#   This file is distributed under the terms of the BSD License (version
#   2). See the COPYING file, which should have been distributed with this
#   file, for details. If you did not receive the COPYING file, see:
#
#   http://www.jmglov.net/opensource/licenses/bsd.txt
#
# cvs-unlock
#
# DESCRIPTION:
#
#   Recursively unlocks a directory and all below it in a CVS repository.
#   The directory must have previously been locked by cvs-lock.
#
#   *A single run of unlock unlocks multiple runs of lock.*
#
# USAGE:
#
#   See usage(), below
#
# EXAMPLES:
#
#   ***
#
# TODO:
#
#   - Why does unlock_dir() fail to detect that the lockfile exists?
#   - Implement unlocking a remote repository using CVS_RSH 
#   - Nothing, this code is perfect
#
# DEPENDENCIES:
#
#   Bourne shell
#
# MODIFICATIONS:
#
#   Josh Glover <jmglov@jmglov.net> (2004/05/28): Initial revision;
#     modified Jennifer Vesperman's cvs-unfreeze.sh script (from O'Reilly's
#     _Essential CVS_): http://examples.oreilly.com/cvs/unfreeze.sh
# =========================================================================

# Constant: ME
#
# Basename of the script

ME=`basename $0`

# Variable: cvsroot
#
# Path to CVS repository (defaults to $CVSROOT environment variable)

cvsroot="${CVSROOT}"

# Variable: dir
#
# Top-level directory in CVS repository to lock

dir=""

# Variable: dryrun
#
# If non-zero, run in dryrun mode

dryrun=0

# Variable: keymagic
#
# Unique key to append to lockfiles

keymagic=""

# Variable: quiet
#
# If non-zero, informational messages will be spewed to STDOUT

quiet=0

# Variable: tmpfile
#
# Temporary file for recording lockfiles

tmpfile=""

# Variable: trace
#
# If non-zero, each command will be spewed to STDOUT before it is run

trace=0

# Variable: unlock_read
#
# Unlock read locks?

unlock_read="rfl"

# Variable: unlock_write
#
# Unlock write locks?

unlock_write="wfl"


# Function: bail_out()
#
# Exit abruptly with an error code after displaying an error message.
#
# Parameters:
#
#   1 - error message to display

bail_out () {

  echo "${ME}: $1"
  rm -f ${tmpfile}
  exit 1

} # bail_out()


# Function: unlock_directory()
#
# Unlocks the specified directory.
#
# Parameters:
#
#   1 - directory to unlock
#
# Returns:
#
#   0 on success, 1 on failure

unlock_directory () {

  if [ ${quiet} -eq 0 ]; then echo "${ME}: unlock: $1"; fi

  # Obtain the master lock
  if [ ${trace} -ne 0 ]; then

    echo mkdir "$1/#cvslock"

  fi # if (trace mode?)

  if [ ${dryrun} -eq 0 ]; then

    mkdir "$1/#cvslock"

  fi # if (dryrun mode?)

  # If we could not get the master lock, return failure
  if [ $? != 0  ]; then return 1; fi

  # Unlock read and or write locks?
  for i in ${unlock_read} ${unlock_write}; do

    # Check for a lockfile
    if [ ${trace} -ne 0 ]; then

      echo test -f "$1/#cvs.$i.${keymagic}"

    fi # if (trace mode?)

    if [ ${dryrun} -eq 0 ]; then

      test -f "$1/#cvs.$i.${keymagic}"

    fi # if (dryrun mode?)

    # If we did not find a lockfile, spew a warning. Otherwise, remove the
    # lockfile
    if [ $? -ne 0 ]; then

      echo "${ME}: unlock: expected to find a lockfile: $1/#cvs.$i.${keymagic}"

    else

      if [ ${trace} -ne 0 ]; then

        echo rm -f "$1/#cvs.$i.${keymagic}"

      fi # if (trace mode?)

      if [ ${dryrun} -eq 0 ]; then

        rm -f "$1/#cvs.$i.${keymagic}"

      fi # if (dryrun mode?)

    fi # if (did we find a lockfile?)

    if [ ${quiet} -eq 0 ]; then

      echo "${ME}: $1/#cvs.$i.${keymagic} unlocked"

    fi # if (spewing debuggery)

  done # for (unlocking read and/or write locks)

  # Release the master lock
  if [ ${trace} -ne 0 ]; then

    echo rmdir "$1/#cvslock"

  fi # if (trace mode?)

  if [ ${dryrun} -eq 0 ]; then

    rmdir "$1/#cvslock"

  fi # if (dryrun mode?)

  return 0

} # unlock_directory()


# Function: unlock_all()
#
# Recursively calls <unlock_dir()> to unlock a whole directory tree.
#
# Returns:
#
#   0 on success, 1 on failure

unlock_all () {

  tmpfile=/tmp/lock.${keymagic}

  for i in `find ${cvsroot}/${dir} -type d ! -iname CVS ! -iname Attic ! -iname "#cvslock"`; do

    # If we cannot unlock this directory, return failure
    if ! unlock_directory $i; then return 1; fi

  done # for (unlocking all directories below ${dir}

  return 0

} # unlock_all()


# Function: usage()
#
# Displays a usage message and exits with the specified code.
#
# Parameters:
#
#   1 - return code (defaults to 255)

usage () {

  retval=$1
  if [ -z "${retval}" ]; then retval=255; fi

  cat <<EOF

Usage: ${ME} {<option>}

  where valid <option>s are:

    -d <root>    CVS repository to use (defaults to ${CVSROOT})
    --dir <dir>  directory relative to CVS root to lock
    --dryrun     do nothing, just show what would be done
    -H,--help    displays this message
    -q           be quiet (suppress informational messages)
    -r           unlock only read locks (defaults to both)
    -t           trace execution and spew trace debuggery
    -w           unlock only write locks (defaults to both)

EOF

  exit ${retval}

} # usage()


# Main program
# -------------------------------------------------------------------------


# Parse args
while [ -n "$1" ]; do

  if [ "$1" = "-d" ]; then

    cvsroot="$2"
    shift; shift
    continue

  fi # if (-d)

  if [ "$1" = "--dir" ]; then

    dir="$2"
    shift; shift
    continue

  fi # if (--dir)

  if [ "$1" = "--dryrun" ]; then

    dryrun=1
    quiet=1
    trace=1
    shift
    continue

  fi # if (--dryrun)

  if [ "$1" = "-H" -o "$1" = "--help" ]; then

    usage 0

  fi # if (-H,--help)

  if [ "$1" = "-q" ]; then

    quiet=1
    shift
    continue

  fi # if (-q)

  if [ "$1" = "-r" ]; then

    unlock_write=""
    shift
    continue

  fi # if (-r)

  if [ "$1" = "-t" ]; then

    trace=1
    shift
    continue

  fi # if (-t)

  if [ "$1" = "-w" ]; then

    unlock_read=""
    shift
    continue

  fi # if (-w)

  # If control reaches here, our option is bogus
  echo "${ME}: invalid option: $1"
  usage

done # while (parsing args)

if [ -z "${cvsroot}" ]; then

  echo "${ME}: No CVSROOT specified in the environment! You must either set the CVSROOT environment variable or use the --cvsroot option."
  usage

fi # if (no ${cvsroot})

if [ -z "${dir}" ]; then

  echo "${ME}: no --dir option, defaulting to unlocking whole ${cvsroot} repository"

fi # if (no ${dir})

if [ ${quiet} -eq 0 ]; then

  cat <<EOF

${ME}: invoked with the following settings:

cvsroot:       ${cvsroot}
dir:           ${dir}
dryrun:        ${dryrun}
quiet:         ${quiet}
trace:         ${trace}
unlock_read:   ${unlock_read}
unlock_write:  ${unlock_write}

EOF

fi # if (spewing debuggery)

if ! [ -d ${cvsroot} ]; then

  bail_out "not a directory: ${cvsroot}"

fi # if (${cvsroot} is not a directory)

keyfile=""
if [ -n "${dir}" ]; then

  keyfile=${cvsroot}/.${dir}

else

  keyfile=${cvsroot}/.cvsroot

fi # if (setting ${keyfile})

if [ ${trace} -ne 0 ]; then

  echo test -f ${keyfile}

fi # if (trace mode?)

if ! test -f ${keyfile}; then

  bail_out "no such file: ${keyfile}; directory does not appear to be frozen"

fi # if (does ${keyfile} exist?)

# Walk through each of the keys that the directory has been locked with
# and unlock each one in turn. *A single run of unlock unlocks multiple
# runs of lock.*
tries=0
for keymagic in `cat ${keyfile}`; do

  if ! unlock_all; then

    echo "${ME}: unable to obtain master locks for all directories"

    let tries=${tries}+1

    if [ ${tries} -gt ${MAXTRIES} ]; then

      bail_out "maximum number of tries (${MAXTRIES}) reached, giving up"

    fi # if (surpassed maximum allowable tries)

    echo "${ME}: sleeping 1 second between tries"

    if [ ${trace} -ne 0 ]; then

      echo sleep 1

    fi # if (trace mode?)

    sleep 1

    echo "${ME}: trying again..."

  else

    if [ ${quiet} -eq 0 ]; then

      echo "${ME}: directory ${dir} unlocked from lock ${keymagic}"

    fi # if (spewing debuggery)

  fi # if (did unlocking succeed?)

done # for (unlocking all locks)

if [ ${quiet} -eq 0 ]; then

  echo "${ME}: CVS repository ${cvsroot} directory ${dir} unlocked"

fi # if (spewing debuggery)

if [ ${trace} -ne 0 ]; then

  echo rm -f ${keyfile}

fi # if (trace mode?)

if [ ${dryrun} -eq 0 ]; then

  rm -f ${keyfile}

fi # if (dryrun mode?)

# Victory!
exit 0


# -------------------------------------------------------------------------