Prepare Scripts

Prepare scripts are run during the preparation phase (see the commit process for more information).

The commit view will not be displayed until the prepare script is complete. The script can modify the contents of the working copy as necessary and the changes will be picked up by Cornerstone and presented to the user in the commit view.

A prepare script can be run in one of two ways:

1. Once for the entire working copy

   The script is run once. The POSIX path of the working copy’s top folder is passed to the script as its only parameter.

   Prepare scripts are run regardless of whether any candidate items are found in the items selected in the working copy browser.

2. Once for each changed item in the user’s selection

   The script is run multiple times, once for each changed item in the files or folders selected by the user in the working copy browser. The POSIX path of the changed item is passed to the script as its only parameter.

   Cornerstone will abort script execution as soon as the first error is encountered.

Selecting a Script for Execution

The prepare script is defined globally for the app. To specify which script is run:

Possible Uses for Prepare Scripts

• Archiving documents as .zip files ready for commit in order to workaround issues with package-format documents placed under version control.

  Documents are manually unzipped for editing and then archived by the script before commit.

• Searching the working copy for text (e.g. NSLog or TODO) in candidate changed files. The script raises an error if the text is found to prevent temporary or incomplete code from being committed.

• Verifying that the names of newly-added files conform to a particular convention.

• Verifying that files conform to a project’s formatting conventions, e.g.:

  • Files do not contain tab characters
  • Files contain a standard header
  • Files contain copyright information

Example Script

#!/usr/bin/env bash

# Finds instances of "NSLog" in the specified file. Reports error and exits
# with exit code 1 if "NSLog" is found.
#
# Usage:
#   CheckForNSLogs file
#
# Arguments:
#   $1 path to the file to search

# Use grep to search for instances of 'NSLog' in the specified file

if [ $(grep -c "NSLog" "$1") -ne 0 ]
then

  # The file contains one or more NSLogs. Use awk to get the line numbers 
  # of the NSLog instances and format them into a comma-separated string

  lines=$(awk 'BEGIN{ORS=", "}/NSLog/{print NR}' "$1" | \
          awk '{sub(/, +$/, ""); print}')
          
  name=${1##*/}
  
  # Echo the name of the file and line numbers to stderr in order
  # that it is displayed to the user by Cornerstone
  
  msg="\"$name\" contains NSLogs on line(s) $lines."
  msg="$msg All NSLogs should be removed before this file is committed."
  
  echo $msg >&2
  
  # Raise an error by exiting with non-zero exit code
  
  exit 1 
  
else
  
  # No NSLogs found so we can continue with the commit
  
  exit 0
  
fi

$1 is used to reference the path of the changed item that is a candidate for committing. It is supplied as the script’s single argument. It is recommended that $1 be placed in quotation marks in order that the script functions correctly with paths containing space characters.