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.

The user is prompted when a prepare script raises an error—i.e. exits with a value other than zero—with the option to continue or cancel the commit.

Prepare scripts can therefore be used to validate changes before a commit.

Selecting a Script for Execution

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

  1. Open the app’s preferences by selecting Preferences... (key equivalent ⌘,) from the Cornerstone menu.

  2. Switch to the Working Copies pane.

  3. Use the Run Script field in the Before Committing... section to choose the prepare script to run.

  4. Specify whether the script should be run once for the entire working copy or once for each item.

Possible Uses for Prepare Scripts

Example Script

Purpose Scan the input file for instances of "NSLog" and generate an error if a match is found
Type Item
Argument Path to a text file
#!/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.

The script formats a useful error message and writes it to stderr. Cornerstone picks up this output and displays it to the user.