lib/helpers: new function _bash_it_find_kin()

New function to do a search looking for a sibling to a parent of the current directory, for example to find `../../.git` to indicate that `$PWD` is inside a git repository.

Author: gaelicWizard

lib/helpers.bash

@@ -837,3 +837,23 @@ then
     fi
   }
 fi
+
+function _bash_it_find_kin()
+(
+# We're deliberately using a subshell for this entire function for simplicity.
+# By using a subshell, we can use ${PWD} without special handling, and can
+#  just `cd ..` to move up the directory heirarchy. Let the shell do the work.
+	local common_ancestor="${PWD}"
+	local uncle="${1?${FUNCNAME[0]}: a file to locate must be specified}" aunt="${2:-}"
+	while [[ "${PWD:-/}" != '/' ]]
+	do
+		if [[ -r "${PWD}/${uncle}" || -r "${aunt:+${PWD}/}${aunt:-}" ]]
+		then
+			common_ancestor="${PWD}"
+			echo "${common_ancestor}"
+			return 0
+		fi
+		command cd .. || return 2
+	done
+	return 1
+)