SourceTree Custom Action alerts: choosing a trigger boundary without notification noise

Answer

**1. What does a SourceTree Custom Action receive?**

• When you create a custom action, SourceTree expands a small set of placeholders before launching the script. The most common ones are:
  • %repo% – absolute path to the repository root
  • %branch% – name of the current branch
  • %remote% – name of the remote that was used (e.g. origin)
  • %operation% – the Git operation that the action is attached to (e.g. commit, pull, push)
• These placeholders are substituted by SourceTree; the script is then executed by the system shell (/bin/sh on macOS/Linux, cmd.exe or powershell.exe on Windows) with the repository root as the current working directory.
• No placeholder for the exit status of the Git command is provided. If you need that information, you must capture it yourself inside the script (e.g. by running the Git command directly or by using a Git hook).
• SourceTree does not inject Git‑specific environment variables such as GIT_DIR unless you set them manually.

**2. Automatic triggers – Git hooks vs. custom actions**

• Custom actions are menu items; they run only when the user explicitly selects them. There is no built‑in event that fires automatically after every fetch, pull, or commit.
• To get an always‑on notification system you need to rely on Git’s own hooks. The relevant hooks are:
  • post-commit – after a commit is created
  • post-merge – after a merge (which is what a pull does when it merges) – this can be used to detect a successful or failed pull
  • pre-push – before a push is sent to the remote
• There is no post-pull hook in Git; the pull operation is a combination of fetch and merge, so post-merge is the closest hook for detecting the outcome of a pull.
• Git hooks run for any Git client, not just SourceTree. They can be bypassed by running Git commands with --no-verify, but they are the most reliable way to cover all local operations.

**3. Threshold for notifications**

• Decide on two simple criteria that will trigger a desktop notification:
  • Non‑zero exit status of the Git operation – indicates a failure (e.g. merge conflict, authentication error).
  • Operation targeting a protected branch – e.g. main, release/*, or any branch that matches a user‑defined regex.
• All other events should be written to a local log file (e.g. ~/.sourcetree/alerts.log) with a minimal payload: repository name, branch, operation, exit status, timestamp.
• Example of a simple filter script (pseudo‑code):

  #!/usr/bin/env bash
  REPO=$1
  BRANCH=$2
  OP=$3
  EXIT=$4
  TIMESTAMP=$(date +%s)
  
  # Decide whether to notify
  if [[ $EXIT -ne 0 || $BRANCH =~ ^release/ ]]; then
    # macOS notification
    osascript -e "display notification '[$REPO] $OP failed on $BRANCH' with title 'SourceTree Alert'"
  else
    echo "$TIMESTAMP	$REPO	$BRANCH	$OP	$EXIT" >> ~/.sourcetree/alerts.log
  fi
  

**4. Practical checklist**

1. Write a filter script that accepts the arguments above and implements the logic from section 3.
2. Make the script executable and place it in a shared directory.
3. Configure the same script as the body of the Git hooks you want to use (e.g. .git/hooks/post-commit, .git/hooks/post-merge, .git/hooks/pre-push).
4. If you still want a manual “quick‑alert” option, add a custom action that calls the script with the placeholders. Note that the script will not receive the exit status of the preceding operation; you would need to invoke the Git command inside the script to capture it.
5. Adjust OS notification settings (macOS Notification Center, Windows Focus Assist) to silence banner pop‑ups while keeping the log file available.

**5. Uncertainty and verification**

• The exact set of placeholders is documented in SourceTree’s help but is not exhaustive; newer versions may expose additional ones.
• There is no official placeholder that expands to the exit status of the Git command. If you need that value, the script must run the Git command itself or rely on a Git hook.
• Testing the script in your environment (e.g. echo the placeholders to a file) is the quickest way to confirm the context.

Missing Diagnostic Detail

Could you confirm which SourceTree version you’re using (e.g. 3.5.x, 3.6.x, or a newer 4.x release)? The placeholder set and hook support can vary slightly between releases, and the answer above assumes a recent 3.x or later build.