From 22c6ffe45727105a19a21744364c15bf92dde2b6 Mon Sep 17 00:00:00 2001
From: "Roscoe A. Bartlett" <rabartl@sandia.gov>
Date: Thu, 10 Oct 2024 14:10:24 -0400
Subject: [PATCH] Fix up and better document to-python3.sh (#610)

Now this is safer to run on a project's entire source tree and it is
documented to explain what this is for.
---
 tribits/refactoring/to-python3.sh | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/tribits/refactoring/to-python3.sh b/tribits/refactoring/to-python3.sh
index 2a295f5f6..4c40c0d67 100755
--- a/tribits/refactoring/to-python3.sh
+++ b/tribits/refactoring/to-python3.sh
@@ -1,12 +1,23 @@
 #!/bin/sh
 #
+# Refactor a TriBITS project's CMake files for the change from
+# find_package(PythonInterp) to find_package(Python3) (see CHANGELOG.md entry
+# for 2024-10-08).
+#
 # Usage:
 #
 #   to-python3.sh <base-dir>
 #
+# NOTES:
+# * This is safe to run multiple times on the same set of files.
+# * This is safe to run from the base project source tree.
+# * This will exclude any files under '.git/'
+# * This will exclude any files under 'tribits/' directories (so it will not mess up TriBITS)
+#
 
 _SCRIPT_DIR=`echo $0 | sed "s/\(.*\)\/to-python3[.]sh/\1/g"`
 baseDir=$1
 find ${baseDir} -type f \
   \( -name CMakeLists.txt -or -name "*.cmake" -or -name "*.cmake.in" -or -name "*.rst" \) \
+  ! -wholename "*/.git/*" ! -wholename  "*/tribits/*" \
   -exec $_SCRIPT_DIR/token-replace.py -t PYTHON_EXECUTABLE -r Python3_EXECUTABLE -f {} ';'