ove

#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
#
# MIT License
#
# Copyright (c) 2019 Ericsson
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is furnished
# to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice (including the next
# paragraph) shall be included in all copies or substantial portions of the
# Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
# OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
# OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

__i=0
case $- in
	*i*) __i=1;;
esac
if [ "${__i}" -eq 1 ]; then
	# shellcheck disable=SC2009
	__p=$(\ps | \grep -w $$ | \grep -v grep)
	if [ "${__p#*bash}" = "$__p" ]; then
		echo 'error: run this in bash'
		unset __i
		unset __p
		return 1
	fi
	unset __p
fi
unset __i

function ove_version_check_early {
	local ret=0

	if command -v dpkg > /dev/null; then
		if ! \dpkg --compare-versions ${BASH_VERSINFO[0]}.${BASH_VERSINFO[1]} ge 4.3; then
			ret=1
		fi
	else
		if [ ${BASH_VERSINFO[0]} -lt 4 ]; then
			ret=1
		elif [ ${BASH_VERSINFO[0]} -eq 4 ] && [ ${BASH_VERSINFO[1]} -lt 3 ]; then
			ret=1
		fi
	fi

	if [ ${ret} -ne 0 ]; then
		echo "error: bash ${BASH_VERSINFO[0]}.${BASH_VERSINFO[1]} is too old. I need bash>=4.3" 1>&2
	fi

	return ${ret}
}

if ! ove_version_check_early; then
	return 1
fi

function ove_read_config_validate_name {
	local re="^[a-zA-Z_]{1,}[a-zA-Z0-9_]{0,}$"
	local var="$1"

	if ! [[ "${var}" =~ ${re} ]]; then
		return 1
	fi

	return 0
}

# remember and set duplicate configs
function ove_read_config_pre {
	local f
	local p
	local p_arr
	local val
	local var
	declare -A a_hash

	if [ "${OVE_CONFIG_DUPLICATES}" != "" ]; then
		unset OVE_CONFIG_DUPLICATES
	fi

	for f in "$@"; do
		if [ ! -e "${f}" ]; then
			continue
		fi

		while read -r p; do
			# ignore comments and empty lines
			if [[ ${p} == \#* ]] || [[ ${p} == '' ]]; then
				continue
			fi
			read -a p_arr -r <<<"${p}"
			var=${p_arr[0]}
			if test "${a_hash["${var}"]+isset}"; then
				val=${p_arr[*]:1}
				# escape all "
				val=${val//\"/\\\"}
				if ! eval ${var}=\"${val}\" 2> /dev/null; then
					echo "warning: config '${var}' could not be set:" 1>&2
					${ove_cmd2pathname["grep"]:?} -w ^${var} -H -n ${1} 1>&2
					continue
				fi
				# shellcheck disable=SC2163
				export ${var}

				# remember duplicates
				if [ "${OVE_CONFIG_DUPLICATES}" = "" ]; then
					OVE_CONFIG_DUPLICATES="$var"
				else
					OVE_CONFIG_DUPLICATES+=" $var"
				fi
				export OVE_CONFIG_DUPLICATES

				# remember configs
				if [ "${OVE_CONFIG_ALL}" = "" ]; then
					OVE_CONFIG_ALL="$var"
				else
					OVE_CONFIG_ALL+=" $var"
				fi
				export OVE_CONFIG_ALL
			fi
			a_hash["${var}"]=1
		done<${f}
	done
}

function ove_read_config {
	local p
	local p_arr
	local re
	local restore
	local val
	local var
	declare -A c

	if [ ! -s "$1" ]; then
		return 1
	fi

	restore=0
	if [[ $- != *f* ]]; then
		restore=1
	fi
	# disable pathname expansion
	set -o noglob

	while read -r p; do
		# ignore comments and empty lines
		if [[ ${p} == \#* ]] || [[ ${p} == '' ]]; then
			continue
		fi

		read -a p_arr -r <<<"${p}"
		var=${p_arr[0]}

		if [ $# -eq 1 ] && ! ove_read_config_validate_name ${var}; then
			echo "error: config name '${var}' is not allowed:" 1>&2
			${ove_cmd2pathname["grep"]:?} -w ^${var} -H -n ${1} 1>&2
			continue
		fi

		if [ "$2" = "clean" ]; then
			unset ${var} 2> /dev/null
			continue
		fi

		# duplicates within one config file
		if [[ -v c[${var}] ]]; then
			ove_echo_warning_noprefix "found config '$var' duplicate in '$1'"
			echo "$var=${p_arr[*]:1} (ignored)" 1>&2
			continue
		fi
		c[$var]=1

		# duplicates across config files
		re=\\b${var}\\b
		if [[ "${OVE_CONFIG_DUPLICATES}" =~ ${re} ]]; then
			continue
		fi

		val=${p_arr[*]:1}
		# escape all "
		val=${val//\"/\\\"}
		if ! eval ${var}=\"${val}\" 2> /dev/null; then
			ove_echo_warning_noprefix "config '${var}' could not be set:" 1>&2
			${ove_cmd2pathname["grep"]:?} -w ^${var} -H -n ${1} 1>&2
			continue
		fi
		# shellcheck disable=SC2163
		export ${var}

		# remember configs
		if [ "${OVE_CONFIG_ALL}" = "" ]; then
			OVE_CONFIG_ALL="$var"
		else
			OVE_CONFIG_ALL+=" $var"
		fi
		export OVE_CONFIG_ALL
	done <$1

	if [ $restore -eq 1 ]; then
		# restore pathname expansion
		set +o noglob
	fi
}

function ove_unsource_user_env {
	# cleanup PATH
	if [ "${OVE_STAGE_DIR}" != "" ] && \
		[[ ${PATH} == *"${OVE_STAGE_DIR}"* ]]; then
		PATH=${PATH/${OVE_STAGE_DIR}${OVE_PREFIX}\/bin:/}
		PATH=${PATH/${OVE_STAGE_DIR}${OVE_PREFIX}\/sbin:/}
	fi

	# cleanup LD_LIBRARY_PATH
	if [ -n "${LD_LIBRARY_PATH}" ] && [ -n "${OVE_LD_LIBRARY_PATH}" ]; then
		LD_LIBRARY_PATH=${LD_LIBRARY_PATH/${OVE_LD_LIBRARY_PATH}/}
		if [ "${LD_LIBRARY_PATH}" = "" ]; then
			unset LD_LIBRARY_PATH
		elif [ ${LD_LIBRARY_PATH:0:1} = ":" ]; then
			LD_LIBRARY_PATH=${LD_LIBRARY_PATH:1}
		fi
	fi

	# cleanup PKG_CONFIG_PATH
	if [ -n "${PKG_CONFIG_PATH}" ] && [ -n "${OVE_PKG_CONFIG_PATH}" ]; then
		PKG_CONFIG_PATH=${PKG_CONFIG_PATH/${OVE_PKG_CONFIG_PATH}/}
		if [ "${PKG_CONFIG_PATH}" = "" ]; then
			unset PKG_CONFIG_PATH
		elif [ ${PKG_CONFIG_PATH:0:1} = ":" ]; then
			PKG_CONFIG_PATH=${PKG_CONFIG_PATH:1}
		fi
	fi

	# cleanup MAKEFLAGS
	if [ -n "${MAKEFLAGS}" ] && \
		[[ ${MAKEFLAGS} == *"${OVE_MAKEFLAGS}"* ]]; then
		MAKEFLAGS=${MAKEFLAGS/${OVE_MAKEFLAGS}/}
		if [ "${MAKEFLAGS}" = "" ]; then
			unset MAKEFLAGS
		elif [ "${MAKEFLAGS: -1}" = " " ]; then
			MAKEFLAGS=${MAKEFLAGS::-1}
		fi
	fi
}

function ove_unsource {
	local f

	ove_unsource_user_env

	# clean config variables
	for f in ${OVE_CONFIG_FILES_ALL}; do
		if [ -e "${f}" ]; then
			ove_read_config ${f} clean
		fi
	done

	# unset any ove[-_] functions
	unset -f $(compgen -A function | \
		\grep -E '^ove($|[-_])' | \
		\grep -E -v "ove_read_config|ove-unsource|${FUNCNAME[0]}|ove_version_check_early" | \
		\awk '{print $1}')

	# unset any ove_/OVE_ variables
	unset $(set -o posix ; set | \
		\grep -i ^ove_ | \
		\cut -d= -f1)

	# unalias any ove[-_] alias
	f=$(compgen -A alias | \
		\grep -E '^ove($|[-_])')
	if [ "$f" != "" ]; then
		unalias $f
	fi

	# unset completion for ove
	if complete -p | \grep -q ' ove$'; then
		complete -r ove
	fi
}

# unsource: :clean up all OVE vars/funcs from this shell:CORE
function ove-unsource {
	ove_entry || return

	ove_unsource
	# unset leftovers and myself
	unset -f $(compgen -A function | \
		\grep -E '^ove($|[-_])' | \
		\awk '{print $1}') \
		${FUNCNAME[0]}
}

# interactive shell? clean up
if [[ $- == *i* ]]; then
	ove_unsource
fi

function ove_welcome_msg {
	local script_ver

	ove-version
	if ! [ -e "${HOME}/.ove.bash" ]; then
		echo
		echo "Do you want to skip the initial 'source ove' step? Run this:"
		echo " cp -a ${OVE_DIR}/ove.bash ${HOME}/.ove.bash && echo '[ -f ~/.ove.bash ] && source ~/.ove.bash' >> ${HOME}/.bashrc"
	fi

	# shellcheck disable=SC2016
	script_ver=$(${ove_cmd2pathname["script"]:?} --version 2> /dev/null | \
		${ove_cmd2pathname["awk"]:?} '{print $NF}')
	if [[ ${script_ver} =~ ^2.3[12] ]]; then
		echo
		ove_echo_note_noprefix "due to a bug in ${ove_cmd2pathname["script"]:?} 2.31/2.32 (you have ${script_ver}), it's not possible to Ctrl-C any OVE command. Upgrade package: '$(ove_command_to_package script)'."
	fi
}

function ove_version_check {
	local ret=0
	local git_arr
	local git_ver
	local git_opts
	local major
	local minor
	local patch

	git_ver=$(${ove_cmd2pathname["git"]:?} --version)
	git_ver=${git_ver/git version /}
	IFS='.' read -r -a git_arr <<< "${git_ver}"

	major=${git_arr[0]}
	minor=${git_arr[1]}
	patch=${git_arr[2]}

	if command -v dpkg > /dev/null; then
		if ! \dpkg --compare-versions ${major}.${minor}.${patch} ge 1.8.5; then
			ret=1
		fi
	elif [ ${major} -lt 2 ]; then
		if [ ${major} -eq 1 ] && [ ${minor} -lt 8 ]; then
			ret=1
		elif [ ${major} -eq 1 ] && [ ${minor} -eq 8 ] && [ ${patch} -lt 5 ]; then
			ret=1
		elif [ ${major} -eq 0 ]; then
			ret=1
		fi
	fi

	if [ ${ret} -ne 0 ]; then
		ove_echo_error_noprefix "git ${git_ver} is too old. I need >=1.8.5"
		return ${ret}
	fi

	# --no-optional-locks was introduced in 2.15.0
	if command -v dpkg > /dev/null; then
		if \dpkg --compare-versions ${major}.${minor}.${patch} ge 2.15.0; then
			git_opts="--no-optional-locks"
		fi
	elif [ ${major} -ge 3 ]; then
		git_opts="--no-optional-locks"
	elif [ ${major} -eq 2 ] && [ ${minor} -lt 15 ]; then
		:
	elif [ ${major} -lt 2 ]; then
		:
	else
		git_opts="--no-optional-locks"
	fi

	OVE_GIT_OPTIONS="${git_opts}"
	export OVE_GIT_OPTIONS

	return ${ret}
}

function ove_main {
	ove_externals_init

	# some error messages use colors. I.e. keep this early
	export OVE_COLOR_GREEN="\033[0;32;7m"
	export OVE_COLOR_CYAN="\033[0;36;7m"
	export OVE_COLOR_BLUE="\033[0;34;7m"
	export OVE_COLOR_YELLOW_X="0;33;7m"
	export OVE_COLOR_YELLOW="\033[${OVE_COLOR_YELLOW_X}"
	export OVE_COLOR_RED="\033[0;31;7m"
	export OVE_COLOR_BLANK="\033[0m"

	# set OVE_OS_* variables ('ove_deps' need them)
	ove_determine_dist_version_and_pack_manager

	# dependency checks
	if ! ove_deps; then
		ove-unsource
		return 1
	fi

	# OVE_USER:the user that runs OVE commands
	OVE_USER=
	if [ "${USER}" != "" ]; then
		OVE_USER="${USER}"
	elif [ "${LOGNAME}" != "" ]; then
		OVE_USER="${LOGNAME}"
	elif command -v whoami > /dev/null; then
		OVE_USER="$(${ove_cmd2pathname["whoami"]:?})"
	else
		OVE_USER="ove"
	fi
	export OVE_USER

	# OVE_TMP:temporary directory for all OVE workspaces (per user)
	OVE_TMP=/tmp/${OVE_USER}/ove
	export OVE_TMP
	if ! [ -d "${OVE_TMP}" ]; then
		if ! ${ove_cmd2pathname["mkdir"]:?} -p "${OVE_TMP}" 2> /dev/null; then
			if ! OVE_TMP="$(${ove_cmd2pathname["mktemp"]:?} -d)"; then
				ove_echo_error_noprefix "weird! '/tmp' is missing/none-writable and 'mktemp -d' fails"
				ove-unsource
				return 1
			fi
		fi
	fi

	# run 'ove init' if this is not a workspace (interactive shells)
	if [[ $- == *i* ]]; then
		# turn off monitor mode to get rid of "Done" messages
		set +m

		if [ -e ".owel" ] && [ -e ove ]; then
			:
		else
			ove-init
		fi
	fi

	# init workspace
	if ! ove_init; then
		ove-unsource
		return 1
	fi

	# welcome and post checks (interactive shells)
	if [[ $- == *i* ]]; then
		if [ ${OVE_LOGLEVEL} -eq 0 ] || [[ "$*" == *"hush"* ]]; then
			:
		else
			ove_welcome_msg
		fi

		ove_post_checks

		# turn on monitor mode
		set -m
	fi
}

# $1: pid
function ove_strace_execve_one_pid {
	local cmd
	local exit_code
	local line
	local syscall
	local t0

	cmd=
	pid=$1
	while read -r line; do
		if [ "${line}" = "" ]; then
			continue
		elif [[ "${line}" == *"ENOENT"* ]]; then
			continue
		fi
		syscall=${line#* }
		syscall=${syscall%%(*}
		if [ "${syscall}" != "execve" ]; then
			continue
		fi

		# for slow string substitution in bash
		if [ ${#line} -gt 1000 ]; then
			cmd=$(echo $line | ${ove_cmd2pathname["cut"]:?} -d'[' -f2 | \
				${ove_cmd2pathname["cut"]:?} -d']' -f1 | \
				${ove_cmd2pathname["sed"]:?} -e 's,"\, ", ,g' )
			cmd=${cmd:1:-1}
		else
			cmd=${line##* [\"}
			cmd=${cmd%%\"]*}
			cmd=${cmd//\", \"/ }
		fi

		if [ "${cmd}" = "" ]; then
			continue
		fi

		exit_code=$(ove_strace_get_exit_code ${pid})
		if [ ${OVE_LOGLEVEL} -eq 3 ]; then
			t0=$(ove_strace_get_t0 ${pid})
			echo "${t0}:${pid}:${exit_code}:${cmd}"
		elif [ ${OVE_LOGLEVEL} -eq 4 ]; then
			echo "$(ove_strace_get_duration_s ${pid}):${pid}:${exit_code}:${cmd}"
		fi
	done <<< "${all_files[$1]}"
}

# $1: directory with strace pid files
function ove_analyze_strace_execve_timing {
	local all_files
	local f
	local pid

	if [ ! -d "$1" ]; then
		return 1
	fi

	declare -A all_files
	{
		for f in $(${ove_cmd2pathname["find"]:?} $1 -type f); do
			pid=${f##*.}
			all_files[${pid}]="$(<${f})"
			ove_strace_execve_one_pid ${pid} &
		done
		wait
	} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -n$([ ${OVE_LOGLEVEL} -eq 4 ] && echo r)
}

function ove_line2ipv4 {
	${ove_cmd2pathname["grep"]:?} -E -o '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}' <<<"$@"
}

# $1: IPv4 address
function ove_ip2host {
	local ip
	local ip_lookup

	if ! ove_check_command "dig"; then
		return 1
	fi

	ip=${1}

	if [[ ${ip} == 127* ]]; then
		ip_lookup="localhost"
	else
		ip_lookup=$(${ove_cmd2pathname["dig"]:?} +short -x ${ip} | \
			${ove_cmd2pathname["tr"]:?} '\n' ' ' | \
			${ove_cmd2pathname["xargs"]:?})

		if [ "${ip_lookup}" = "" ]; then
			ip_lookup="NA"
		else
			ip_lookup=${ip_lookup::-1}
		fi
	fi

	echo ${ip_lookup}
}

# $1: IPv4 address
function ove_ip2org {
	local ip
	local org

	if ! ove_check_command "whois"; then
		return 1
	fi

	ip=${1}
	if [[ ${ip} == 127* ]]; then
		org="NA"
	else
		org=$(${ove_cmd2pathname["timeout"]:?} 3 \
			${ove_cmd2pathname["whois"]:?} ${ip} 2> /dev/null | \
			${ove_cmd2pathname["grep"]:?} -E -i 'netrange:|netname|parent' | \
			${ove_cmd2pathname["tr"]:?} -s ' ')
		if [ "${org}" = "" ]; then
			return
		fi
	fi

	printf "${org}"
}

# $1: port
function ove_port2service {
	local port
	local port_service

	port=${1}
	if [ "${port}" -eq 0 ]; then
		return 0
	fi

	if [ -e /etc/services ]; then
		# shellcheck disable=SC2016
		port_service=$(${ove_cmd2pathname["grep"]:?} -E -v '^#|^$' /etc/services | \
			${ove_cmd2pathname["awk"]:?} '{print $1, $2}' | \
			${ove_cmd2pathname["grep"]:?} -m1 -w ${port} | \
			${ove_cmd2pathname["awk"]:?} '{print $1}')
	fi

	if [ "${port_service}" = "" ]; then
		port_service="NA"
	fi
	echo "${port_service}"
}

# $1: pid
function ove_strace_connect_one_pid {
	local cmd
	local ip
	local ip_lookup
	local line
	local port
	local port_service
	local ret
	local sa_family
	local str
	local sun_path
	local syscall

	cmd=
	pid=$1
	while read -r line; do
		if [ "${line}" = "" ]; then
			continue
		fi
		syscall=${line#* }
		syscall=${syscall%%(*}

		if [ "${syscall}" = "bind" ] ||
			[ "${syscall}" = "connect" ]; then
			sa_family=${line##*sa_family=}
			sa_family=${sa_family%%,*}
			t0=${line%% *}

			ret=${line##* =}
			ret=${ret% <*}
			if [[ "${ret}" == " -1"* ]] && ! [[ "${ret}" != "EINPROGRESS"* ]]; then
				continue
			fi

			if [ "${sa_family}" = "AF_LOCAL" ] || \
				[ "${sa_family}" = "AF_UNIX" ]; then
				sun_path=${line#*\"}
				sun_path=${sun_path%\"*}

				# abstract sockets
				if [[ "${line}" == *"=@"* ]]; then
					sun_path="@${sun_path}"
				fi

				cmd=$(ove_strace_get_execve ${pid})

				str+="${t0}:${syscall}:${sa_family}:${sun_path}:${cmd}\n"
			elif [ "${sa_family}" = "AF_INET" ]; then
				ip=$(ove_line2ipv4 ${line})
				port=$(${ove_cmd2pathname["cut"]:?} -d'(' -f3- <<<"${line}" | \
					${ove_cmd2pathname["cut"]:?} -d')' -f1)

				ip_lookup=${ove_ip2host_db["${ip}"]}
				port_service=${ove_port2service_db["${port}"]}
				cmd=$(ove_strace_get_execve ${pid})

				str+="${t0}:${syscall}:${sa_family}:${ip}:${ip_lookup}:${port}:${port_service}:${cmd}\n"
			fi
		fi
	done <<< "${all_files[${pid}]}"

	if [ "${str}" != "" ]; then
		printf "${str}"
	fi
}

function ove_read_connect_cache {
	local line

	unset ove_ip2host_db
	unset ove_ip2org_db
	unset ove_port2service_db

	declare -A -g ove_ip2host_db
	declare -A -g ove_ip2org_db
	declare -A -g ove_port2service_db

	if [ -e ${OVE_GLOBAL_STATE_DIR}/ip2host.cache ]; then
		for line in $(${ove_cmd2pathname["cat"]:?} ${OVE_GLOBAL_STATE_DIR}/ip2host.cache); do
			ove_ip2host_db["${line%%:*}"]="${line##*:}"
		done
	fi

	if [ -e ${OVE_GLOBAL_STATE_DIR}/port2service.cache ]; then
		for line in $(${ove_cmd2pathname["cat"]:?} ${OVE_GLOBAL_STATE_DIR}/port2service.cache); do
			ove_port2service_db["${line%%:*}"]="${line##*:}"
		done
	fi

	if [ -e ${OVE_GLOBAL_STATE_DIR}/ip2org.cache ]; then
		while read -r line; do
			ove_ip2org_db["${line%%:*}"]="$(${ove_cmd2pathname["tr"]:?} '@' '\n' <<<"${line#*:}")"
		done < <(${ove_cmd2pathname["cat"]:?} ${OVE_GLOBAL_STATE_DIR}/ip2org.cache)
	fi
}

# $1: directory with strace pid files
function ove_update_connect_db {
	local host
	local f
	local ip
	local line
	local org
	local port
	local service

	ove_read_connect_cache

	if command -v ag > /dev/null; then
		${ove_cmd2pathname["ag"]:?} --nobreak --nofilename -o --nonumbers 'AF_INET,.* =' $1 | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u > ${OVE_OWEL_TMP_DIR}/af_inet
	else
		${ove_cmd2pathname["grep"]:?} -E -R -o -h 'AF_INET,.* =' $1 | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u > ${OVE_OWEL_TMP_DIR}/af_inet
	fi

	if ! [ -s "${OVE_OWEL_TMP_DIR}/af_inet" ]; then
		${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/af_inet
		return
	fi

	while read -r line; do
		ip=$(ove_line2ipv4 ${line})
		if [ "${ip}" = "" ]; then
			continue
		fi
		port=$(${ove_cmd2pathname["cut"]:?} -d'(' -f2- <<<"${line}" | \
			${ove_cmd2pathname["cut"]:?} -d')' -f1)
		if [ "${port}" = "" ]; then
			continue
		elif [[ ! "${port}" =~ ^[0-9]+$ ]]; then
			continue
		fi

		if ! test "${ove_ip2host_db["${ip}"]+isset}"; then
			host="$(ove_ip2host ${ip})"
			if [ "${host}" != "" ]; then
				ove_ip2host_db["${ip}"]="${host}"
				echo "${ip}:${host}" >> ${OVE_GLOBAL_STATE_DIR}/ip2host.cache
			fi
		fi

		if ! test "${ove_ip2org_db["${ip}"]+isset}"; then
			org="$(ove_ip2org ${ip} | ${ove_cmd2pathname["tr"]:?} '\n' '@')"
			if [ "${org}" != "" ]; then
				ove_ip2org_db["${ip}"]="$(echo ${org} | ${ove_cmd2pathname["tr"]:?} '@' '\n')"
				echo "${ip}:${org}" >> ${OVE_GLOBAL_STATE_DIR}/ip2org.cache
			fi
		fi

		if ! test "${ove_port2service_db["${port}"]+isset}"; then
			service="$(ove_port2service ${port})"
			if [ "${service}" != "" ]; then
				ove_port2service_db["${port}"]=${service}
				echo "${port}:${service}" >> ${OVE_GLOBAL_STATE_DIR}/port2service.cache
			fi
		fi
	done <${OVE_OWEL_TMP_DIR}/af_inet

	${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/af_inet

	for f in ${OVE_GLOBAL_STATE_DIR}/{ip2host,ip2org,port2service}.cache; do
		if [ ! -s "$f" ]; then
			continue
		fi
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -V -u -o ${f} ${f} &
	done
	wait
}

# $1: directory with strace pid files
function ove_analyze_strace_raw {
	${ove_cmd2pathname["find"]:?} "$1" \
		-type f \
		-exec cat {} \; | \
		LC_ALL=C ${ove_cmd2pathname["sort"]:?} -nr
}

# $1: directory with strace pid files
function ove_analyze_strace_file {
	local f
	local line
	local re
	local syscall

	re="^[A-Za-z_0-9]+$"
	${ove_cmd2pathname["find"]:?} "$1" -type f -exec cat {} \; | \
		while read -r line; do
			syscall=${line#* }
			syscall=${syscall%%(*}
			if [[ "${line}" == *trace.cont* ]]; then
				continue
			elif [[ "$syscall" =~ ${re} ]]; then
				f=${line#*\"}
				f=${f%\"*}
				if [[ "$line" == *ENOENT* ]]; then
					echo "${line%% *}:ENOENT:$syscall:$f"
				else
					echo "${line%% *}:0:$syscall:$f"
				fi
			fi
		done
}

# $1: directory with strace pid files
function ove_analyze_strace_connect {
	local all_files
	local f
	local pid

	if [ ! -d "$1" ]; then
		return 1
	fi

	declare -A all_files
	ove_update_connect_db $1
	{
		for f in $(${ove_cmd2pathname["find"]:?} $1 -type f); do
			pid=${f##*.}
			all_files[${pid}]="$(<${f})"
			ove_strace_connect_one_pid ${pid} &
		done
		wait
	} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -n
}

# $1: pid
function ove_strace_get_exit_code {
	local exit_code
	local strace_file

	strace_file=${all_files[$1]}
	exit_code=${strace_file##*$'\n'}
	if [[ "${exit_code}" == *"killed by"* ]]; then
		exit_code=${exit_code##* killed by }
		exit_code=${exit_code%% +++}
	elif [[ "${exit_code}" == *"exited with"* ]]; then
		exit_code=${exit_code##* exited with }
		exit_code=${exit_code%% +++}
	else
		exit_code="alive"
	fi

	echo ${exit_code}
}

# $1: pid
function ove_strace_get_duration_s {
	local diff
	local strace_file
	local t0
	local t1

	strace_file=${all_files[$1]}
	t0=${strace_file%% *}
	t1=${strace_file##*$'\n'}
	t1=${t1%% *}

	if [ "${t0}" = "${t1}" ]; then
		echo "0.000000"
		return
	fi

	# shellcheck disable=SC2016
	diff=$(${ove_cmd2pathname["awk"]:?} "BEGIN{printf \"%.6f\n\", (${t1} - ${t0})}")
	echo ${diff}
}

# $1: pid
function ove_strace_get_duration_ms {
	local diff
	local strace_file
	local t0
	local t1

	strace_file=${all_files[$1]}
	t0=${strace_file%% *}
	t1=${strace_file##*$'\n'}
	t1=${t1%% *}

	if [ "${t0}" = "${t1}" ]; then
		echo "0"
		return
	fi

	# shellcheck disable=SC2016
	diff=$(${ove_cmd2pathname["awk"]:?} "BEGIN{printf \"%.0f\n\", (${t1} - ${t0}) * 1000}")
	echo ${diff}
}

# $1: pid
function ove_strace_get_t0 {
	local strace_file
	local t0

	strace_file=${all_files[$1]}
	t0=${strace_file%% *}
	echo ${t0}
}

# $1: pid
function ove_strace_get_execve {
	local cmd
	local line
	local syscall

	while read -r line; do
		if [ "${line}" = "" ]; then
			continue
		fi
		syscall=${line#* }
		syscall=${syscall%%(*}

		if [ "${syscall}" != "execve" ]; then
			continue
		elif [[ "${line}" == *"ENOENT"* ]]; then
			continue
		fi
		# for slow string substitution in bash
		if [ ${#line} -gt 1000 ]; then
			cmd=$(echo $line | \
				${ove_cmd2pathname["cut"]:?} -d'[' -f2 | \
				${ove_cmd2pathname["cut"]:?} -d']' -f1 | \
				${ove_cmd2pathname["sed"]:?} -e 's,"\, ", ,g' )
			cmd=${cmd:1:-1}
		else
			cmd=${line##* [\"}
			cmd=${cmd%%\"]*}
			cmd=${cmd//\", \"/ }
		fi
	done <<< "${all_files[$1]}"

	if [ "${cmd}" = "" ]; then
		cmd="NA"
	fi
	echo -e "${cmd}"
}

# $1: pid
function ove_strace_one_pid {
	local cmd
	local duration_ms
	local duration_s
	local ip
	local ip_lookup
	local ip_org
	local key
	local line
	local out_1
	local out_2
	local p
	local pid
	local port
	local port_service
	local ret
	local sa_family
	local suffix
	local sun_path
	local t

	pid=$1

	duration_ms=$(ove_strace_get_duration_ms ${pid})
	duration_s=$(ove_strace_get_duration_s ${pid})
	t=$(ove_strace_get_t0 ${pid})

	# label START
	out_1="    ${pid} [label=\"\lt: ${t}\lp: ${pid}\ld: ${duration_ms} ms (${duration_s} s)\l"

	# exit code
	exit_code=$(ove_strace_get_exit_code ${pid})
	if [[ "${exit_code}" =~ ^[0-9]+$ ]]; then
		if [ ${exit_code} -ne 0 ]; then
			out_1+="e: ${exit_code}\l"
			border_color='"red"'
		else
			border_color='"green"'
		fi
	elif [ "${exit_code}" = "alive" ]; then
		border_color='"blue"'
	else
		out_1+="e: ${exit_code}\l"
		border_color='"black"'
	fi

	cmd=
	out_2=
	declare -A ip_port_cnt
	declare -A ip_hash
	while read -r line; do
		if [ "${line}" = "" ]; then
			continue
		fi
		syscall=${line#* }
		syscall=${syscall%%(*}
		if ! [[ "${syscall}" =~ ^[a-z0-9]+$ ]]; then
			continue
		fi

		echo "${t}:${syscall}:${pid}:${duration_ms}:${duration_s}" >> ${OVE_OWEL_TMP_DIR}/timing
		if [[ "${syscall}" == clone* ]] ||
			[ "${syscall}" = "fork" ] ||
			[ "${syscall}" = "vfork" ]; then
			p=${line##* = }
			p=${p%% *}
			if ! [[ "${p}" =~ ^[0-9]+$ ]]; then
				continue
			fi
			out_2+="\n    ${pid} -> ${p} [label=${syscall} fontsize=10,fontcolor=black];"
			continue
		elif [ "${syscall}" = "execve" ]; then
			if [[ "${line}" == *"ENOENT"* ]]; then
				continue
			fi
			# for slow string substitution in bash
			if [ ${#line} -gt 1000 ]; then
				cmd=$(echo $line | \
					${ove_cmd2pathname["cut"]:?} -d'[' -f2 | \
					${ove_cmd2pathname["cut"]:?} -d']' -f1 | \
					${ove_cmd2pathname["sed"]:?} -e 's,"\, ", ,g' )
				cmd=${cmd:1:-1}
			else
				cmd=${line##* [\"}
				cmd=${cmd%%\"]*}
				cmd=${cmd//\", \"/ }
			fi
			continue
		elif [ "${syscall}" = "bind" ] ||
			[ "${syscall}" = "connect" ]; then
			sa_family=${line##*sa_family=}
			sa_family=${sa_family%%,*}

			ret=${line##* =}
			ret=${ret% <*}
			if [[ "${ret}" == " -1"* ]] && ! [[ "${ret}" != "EINPROGRESS"* ]]; then
				continue
			fi

			if [ "${sa_family}" = "AF_LOCAL" ] || \
				[ "${sa_family}" = "AF_UNIX" ]; then
				sun_path=${line#*\"}
				sun_path=${sun_path%\"*}

				# abstract sockets
				if [[ "${line}" == *"=@"* ]]; then
					sun_path="@${sun_path}"
				fi

				out_2+="\n    \"${sun_path}\" [label=\"\ls: ${sun_path}\" shape=box3d,fontsize=10,fontcolor=black,style=filled,fillcolor=\"cyan\"];"
				out_2+="\n    ${pid} -> \"${sun_path}\" [label=\"${syscall}\" fontsize=10,fontcolor=black];"
			elif [ "${sa_family}" = "AF_INET" ]; then
				ip=$(ove_line2ipv4 ${line})
				if [ "${ip}" = "" ]; then
					continue
				fi
				port=$(${ove_cmd2pathname["cut"]:?} -d'(' -f3- <<<"${line}" | \
					${ove_cmd2pathname["cut"]:?} -d')' -f1)
				if [ "${port}" = "" ]; then
					continue
				fi

				if test "${ip_port_cnt["${ip}:${port}"]+isset}"; then
					ip_port_cnt["${ip}:${port}"]=$((${ip_port_cnt["${ip}:${port}"]} + 1))
				else
					ip_port_cnt["${ip}:${port}"]=1
				fi

				ip_lookup=${ove_ip2host_db["${ip}"]}
				ip_org=${ove_ip2org_db["${ip}"]}

				org=$(${ove_cmd2pathname["sed"]:?} -e 's/$/ \\l/g' <<<"${ip_org}" | \
					${ove_cmd2pathname["tr"]:?} -d '\n' | \
					${ove_cmd2pathname["tr"]:?} \" \')

				if ! test "${ip_hash["${ip}"]+isset}"; then
					out_2+="\n    \"${ip}\" [label=\"\lIPv4: ${ip}\lhost: ${ip_lookup}\lorg: ${org}\l\" shape=box3d,fontsize=10,fontcolor=black,style=filled,fillcolor=\"yellow\"];"
					ip_hash["${ip}"]=1
				fi
				if [ ${port} -eq 0 ]; then
					out_2+="\n    ${pid} -> \"${ip}\" [label=\"${syscall}\" fontsize=10,fontcolor=black];"
				else
					port_service=${ove_port2service_db["${port}"]}
					out_2+="\n    ${pid} -> \"${ip}\" [label=\"${syscall} ${port}/${port_service}\" fontsize=10,fontcolor=black];"
				fi
			else
				continue
			fi
		fi
	done <<< "${all_files[$1]}"

	for key in "${!ip_port_cnt[@]}"; do
		ip=${key%%:*}
		port=${key##*:}
		ip_lookup="${ove_ip2host_db["${ip}"]}"
		port_service=${ove_port2service_db["${port}"]}
		if [ ${ip_port_cnt[${ip}:${port}]} -gt 1 ]; then
			suffix="(repeated ${ip_port_cnt[${ip}:${port}]} time(s))"
		fi
		out_1+="c: ${ip}|${ip_lookup}|${port}|${port_service} ${suffix}\l"
	done

	# penwidth based on duration
	if [ ${duration_ms} -gt 20 ]; then
		penwidth=3
	elif [ ${duration_ms} -gt 0 ]; then
		penwidth=2
	else
		penwidth=1
	fi

	if [ "${cmd}" != "" ]; then
		out_1+="x: $(set -f; echo -e ${cmd} | \
			${ove_cmd2pathname["fold"]:?} -w 80 -s | \
			${ove_cmd2pathname["sed"]:?} -e 's/$/ \\l/g' | \
			${ove_cmd2pathname["tr"]:?} '\n' ' ' | \
			${ove_cmd2pathname["tr"]:?} \" \')"
	fi

	# label END
	out_1+="\",color=${border_color},penwidth=${penwidth},fontsize=10,fontcolor=black];"

	echo "${out_1}"
	if [ "${out_2}" != "" ]; then
		echo -e "${out_2}"
	fi
}

function ove_command_usage {
	local a
	local description
	local cmd=${FUNCNAME[1]/ove-/}
	local opt

	a=$(${ove_cmd2pathname["grep"]:?} -B1 "^function ove-${cmd} " ${OVE_SELF} | \
		${ove_cmd2pathname["head"]:?} -1)
	opt=$(${ove_cmd2pathname["cut"]:?} -d: -f2 <<<"${a}")
	description=$(${ove_cmd2pathname["cut"]:?} -d: -f3- <<<"${a}")
	echo -e "usage: ove ${cmd} ${opt}\t# ${description}"
}

# strace-graph:dir:run strace graph analysis:DEBUG
function ove-strace-graph {
	ove_entry || return

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	fi

	ove_strace_create_graph $1 ${1##*/}
}

# strace-execve-timeline:dir:run strace execve timeline analysis:DEBUG
function ove-strace-execve-timeline {
	ove_entry || return

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	fi

	OVE_LOGLEVEL=3 ove_analyze_strace_execve_timing $1

}

# strace-execve-time:dir:run strace execve time analysis:DEBUG
function ove-strace-execve-time {
	ove_entry || return

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	fi

	OVE_LOGLEVEL=4 ove_analyze_strace_execve_timing $1
}

# strace-connect:dir:run strace connect time analysis:DEBUG
function ove-strace-connect {
	ove_entry || return

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	fi

	ove_analyze_strace_connect $1
}

# $1: directory with strace pid files
# $2: append string to output files
function ove_strace_create_graph {
	local all_files
	local cmd
	local ext
	local f
	local i
	local o_base
	local o_dot
	local o_svg
	local o_timing
	local opt
	local pid
	declare -A ext_list

	if [ ! -d "$1" ]; then
		return 1
	elif [ $# -ne 2 ]; then
		return 1
	fi

	o_base="${OVE_OWEL_TMP_DIR}/strace-${2}"
	o_dot=${o_base}.dot
	o_svg=${o_base}.svg
	o_timing=${o_base}.timing

	# supported extensions
	ext_list['ascii']=1
	ext_list['boxart']=1
	ext_list['html']=1
	ext_list['pdf']=1
	ext_list['png']=1
	ext_list['svg']=1

	echo "strict digraph $(${ove_cmd2pathname["tr"]:?} '-' '_' <<<"${OVE_OWEL_NAME}" | \
		${ove_cmd2pathname["tr"]:?} -d '.') {" > ${o_dot}
	echo "    node [shape=box];" >> ${o_dot}

	# remove leftovers
	${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR} -name "strace-${2}.dot.*" -print0 | \
		${ove_cmd2pathname["xargs"]:?} -0 rm &> /dev/null

	declare -A all_files
	true > ${OVE_OWEL_TMP_DIR}/timing
	ove_update_connect_db $1
	for f in $(${ove_cmd2pathname["find"]:?} $1 -type f); do
		pid=${f##*.}
		all_files[${pid}]="$(<${f})"
		ove_strace_one_pid ${pid} >> ${o_dot}.${pid} &
	done
	wait

	# merge all files into one
	${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR} -name "strace-${2}.dot.*" -print0 | \
		${ove_cmd2pathname["xargs"]:?} -0 cat >> ${o_dot}
	${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR} -name "strace-${2}.dot.*" -print0 | \
		${ove_cmd2pathname["xargs"]:?} -0 rm

	echo "}" >> ${o_dot}

	# sequence numbers
	i=0
	true > "$OVE_TMP"/sed-script-file
	# shellcheck disable=SC1003
	${ove_cmd2pathname["grep"]:?} \
		-n \
		-E  \
		'^.*\[label=".*lt:' \
		${o_dot} | \
		${ove_cmd2pathname["tr"]:?} '\\' ' ' | \
		LC_ALL=C ${ove_cmd2pathname["sort"]:?} -k5 -n | \
		${ove_cmd2pathname["cut"]:?} -d: -f1 | \
		while read -r no; do
			i=$((i + 1))
			printf "%s\n" "${no}s/\(.*\[label=\"\)\(.*\];\)/\1\\\l\i: ${i}\2/g" >> "$OVE_TMP"/sed-script-file
		done
	if [ -s "$OVE_TMP"/sed-script-file ]; then
		${ove_cmd2pathname["sed"]:?} \
			-i \
			-f "$OVE_TMP"/sed-script-file \
			${o_dot}
	fi
	${ove_cmd2pathname["rm"]:?} "$OVE_TMP"/sed-script-file

	LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u ${OVE_OWEL_TMP_DIR}/timing > ${o_timing}
	${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/timing

	if [ "${OVE_TRACE_GRAPH_VIEWER}" = "" ]; then
		${ove_cmd2pathname["du"]:?} -sh ${o_dot}
	else
		ext_list['ascii']=0
		ext_list['boxart']=0
		ext_list['html']=0
		ext_list['pdf']=0
		ext_list['png']=0
		ext_list['svg']=0
		while IFS=';' read -a opt -r; do
			for o in "${opt[@]}"; do
				if [[ "${o}" != *:* ]]; then
					ove_echo_error_noprefix "colon missing '$o', check 'OVE_TRACE_GRAPH_VIEWER' config"
					return 1
				elif [ ! "${ext_list["${o%:*}"]+isset}" ]; then
					ove_echo_error_noprefix "'${o%:*}' is not a supported file extension"
					continue
				fi
				ext_list["${o%:*}"]=1
			done
		done <<<"${OVE_TRACE_GRAPH_VIEWER}"
		if [[ "${ext_list[*]}" != *1* ]]; then
			return 1
		fi
	fi

	if command -v dot > /dev/null; then
		for f in svg pdf png; do
			if [ "${ext_list[${f}]}" -eq 0 ]; then
				continue
			elif ! ${ove_cmd2pathname["dot"]:?} -T${f} ${o_dot} > ${o_base:?}.$f; then
				return 1
			elif [ "${OVE_TRACE_GRAPH_VIEWER}" = "" ]; then
				${ove_cmd2pathname["du"]:?} -sh ${o_base:?}.$f
			fi
		done
	fi

	if command -v graph-easy > /dev/null; then
		for f in html boxart ascii; do
			if [ "${ext_list[${f}]}" -eq 0 ]; then
				continue
			elif ! ${ove_cmd2pathname["graph-easy"]:?} \
				--from=dot \
				--as="$f" \
				< ${o_dot} > ${o_base:?}.$f 2> /dev/null; then
				return 1
			elif [ "${OVE_TRACE_GRAPH_VIEWER}" = "" ]; then
				${ove_cmd2pathname["du"]:?} -sh ${o_base:?}.$f
			fi
		done
	fi

	if [ "${OVE_TRACE_GRAPH_VIEWER}" != "" ]; then
		while IFS=';' read -a opt -r; do
			for o in "${opt[@]}"; do
				ext="${o%:*}"
				cmd="${o#*:}"
				if [ -s "${o_base:?}.${ext}" ] && command -v "${cmd}" > /dev/null; then
					# launch viewer
					"${cmd}" "${o_base:?}.${ext}"
				fi
			done
		done <<<"${OVE_TRACE_GRAPH_VIEWER}"
	fi

	return 0
}

# helper for tmux related commands
function ove_sanity_check_tmux {
	local tmux_default_shell
	local tmux_socket

	if [ -z "${TMUX}" ]; then
		return 1
	fi
	tmux_socket=${TMUX%%,*}
	if [ "$tmux_socket" = "" ]; then
		ove_echo_fatal_noprefix "variable TMUX=$TMUX does not contain a valid socket"
		return 1
	elif [ ! -w "$tmux_socket" ]; then
		ove_echo_error_noprefix "tmux socket '$tmux_socket' is not writable by '$OVE_USER'"
		return 1
	elif ! tmux_default_shell=$(${ove_cmd2pathname["tmux"]:?} show-options -gv default-shell); then
		return 1
	elif ! [[ "${tmux_default_shell}" == *bash* ]]; then
		ove_echo_error_noprefix "tmux default shell '${tmux_default_shell}' is not bash"
		return 1
	fi

	return 0
}

# $1: timeout in seconds
# $2: files to watch. Passed on to inotifywait --fromfile
function ove_inotifywait {
	local ret

	if [ ! -e ${2} ]; then
		return 1
	elif [ $(${ove_cmd2pathname["wc"]:?} -l < ${2}) -eq 0 ]; then
		return 1
	fi

	${ove_cmd2pathname["sleep"]:?} 0.01
	${ove_cmd2pathname["inotifywait"]:?} \
		-t ${1} \
		-qq \
		--event modify \
		--event delete_self \
		--event create \
		--event delete \
		--fromfile ${2}
	ret=$?

	${ove_cmd2pathname["sleep"]:?} 0.01
	if [ ${ret} -eq 1 ]; then
		return 1
	else
		return 0
	fi
}

function ove_inotify_cleanup {
	${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR}/ -name "inotifywait-*-${1}*" -exec rm {} \;
}

# $1  : timeout in sec
# $2  : use inotifywait (0 or 1)
# $3  : max count
# $4..: command
function ove_loop_command {
	local all_files
	local cmd
	local f
	local f_early
	local f_early_all
	local f_stderr
	local files_modified_by_command
	local i
	local j
	local max_count
	local prefix
	local read_args
	local inotifywait_pid
	local s
	local sed_expr
	local _timeout
	local use_inotify

	if [ $# -lt 4 ]; then
		return 1
	fi

	_timeout=$1
	use_inotify=$2
	max_count=$3
	shift 3
	(( i=0 ))
	while true; do
		if ! ove_verify_checksums && ! ove_reinit; then
			read -r -p "" -t 3
			continue
		fi
		(( i+=1 ))
		if [ ${max_count} -ne 0 ] && [ ${i} -gt ${max_count} ]; then
			break
		fi
		clear
		if [ "${OVE_TMUX_PANE_HEADER}" = "wide" ]; then
			ove_echo_cyan_error "${OVE_OWEL_NAME}:ove-${*} [c:${i} t:${_timeout} i:${use_inotify} m:${max_count}]"
		elif [ "${OVE_TMUX_PANE_HEADER}" = "short" ]; then
			ove_echo_cyan_error_noprefix "$(${ove_cmd2pathname["date"]:?} '+%Y-%m-%d %H:%M:%S'):ove-${*}"
		elif [ "${OVE_TMUX_PANE_HEADER}" = "off" ]; then
			:
		fi

		# inotify: first iteration?
		if [ ${use_inotify} -eq 1 ] && [ ${i} -eq 1 ]; then
			all_files=$(${ove_cmd2pathname["mktemp"]:?} -u -p ${OVE_OWEL_TMP_DIR} inotifywait-fromfile-XXXXXXXXXX)

			# trap to be able to cleanup files
			# shellcheck disable=SC2064
			trap "ove_inotify_cleanup ${all_files: -10}" EXIT

			# start inotifywait in monitor mode in the background
			# monitor all files (for now)
			# shellcheck disable=SC2016
			cmd='for f in $(ove_repo_cmd ${repo} ls-files); do [ -f ${f} ] && echo ${PWD}/${f}; done; [ -e ${PWD}/.git ] && echo ${PWD}/.git'
			ove_revtab_forall_parallel "${cmd}" > ${all_files}

			# extra files/directories to monitor?
			if [ "${OVE_LOOP_INOTIFY_EXTRA}" != "" ]; then
				${ove_cmd2pathname["find"]:?} ${OVE_LOOP_INOTIFY_EXTRA//;/ } -type f >> ${all_files}
			fi

			cmd="${1%% *}"
			files_modified_by_command="${OVE_OWEL_TMP_DIR}/inotifywait-${cmd}-${all_files: -10}"
			f_stderr="${files_modified_by_command}-stderr"
			true > ${f_stderr}
			if [ -e /proc/sys/fs/inotify/max_user_watches ] && [ $(${ove_cmd2pathname["cat"]:?} /proc/sys/fs/inotify/max_user_watches) -lt $(${ove_cmd2pathname["wc"]:?} -l < ${all_files}) ]; then
				ove_echo_error_noprefix "you need to increase the number of inotify user watches. Try:"
				echo
				if [ ${EUID} != 0 ]; then
					prefix="${ove_cmd2pathname["sudo"]:?}"
				fi
				echo "$ ${prefix} ${ove_cmd2pathname["bash"]:?} -c 'echo $(${ove_cmd2pathname["wc"]:?} -l < ${all_files}) > /proc/sys/fs/inotify/max_user_watches'"
				if ove_sanity_check_tmux 2> /dev/null; then
					read -r -p ""
				fi
				return 1
			fi

			# retrieve the lock
			exec {fd}>${OVE_OWEL_TMP_DIR}/.inotify.lock
			${ove_cmd2pathname["flock"]:?} ${OVE_FLOCK_OPTIONS} ${fd}

			# try to check that no other process is accessing our file watch list
			j=0
			f_early="${files_modified_by_command}-early-check"
			f_early_all="${files_modified_by_command}-early-check-all"
			while true; do
				if [ ${j} -eq 10 ]; then
					ove_echo_cyan_noprefix "some other process is accessing the file watch list, if possible stop that and try again"
					echo "File(s):"
					echo "$ ove head-tail ${f_early_all}"
					${ove_cmd2pathname["sort"]:?} -u -o ${f_early_all} ${f_early_all}
					ove-head-tail ${f_early_all}
					if ove_sanity_check_tmux 2> /dev/null; then
						read -r -p "" -t 3
					fi
					# release the lock and try again
					${ove_cmd2pathname["flock"]:?} -u ${fd}
					i=0
					continue 2
				fi
				${ove_cmd2pathname["inotifywait"]:?} -t 1 -q --format '%w%f' --fromfile ${all_files} > ${f_early}
				if ! [ -s ${f_early} ]; then
					break
				fi

				# ignore first 5 iterations
				if [ ${j} -ge 5 ]; then
					${ove_cmd2pathname["cat"]:?} ${f_early} >> ${f_early_all}
				fi
				((j++))
			done

			${ove_cmd2pathname["inotifywait"]:?} \
				-m \
				--format '%w%f' \
				--fromfile ${all_files} > ${files_modified_by_command} 2>> ${f_stderr} &
			inotifywait_pid=${!}

			# wait for inotifywait
			# shellcheck disable=SC2002
			${ove_cmd2pathname["timeout"]:?} 30 tail -f ${f_stderr} | \
				${ove_cmd2pathname["grep"]:?} -E -q "Watches established.|Failed to watch" | \
				{ ${ove_cmd2pathname["cat"]:?}; echo >> ${f_stderr}; }
			if [ ${PIPESTATUS[0]} -eq 124 ]; then
				if [ -s "${f_stderr}" ]; then
					${ove_cmd2pathname["cat"]:?} ${f_stderr}
				fi
				ove_echo_error_noprefix "inotifywait did not established watches within 30 sec"
				if ove_sanity_check_tmux 2> /dev/null; then
					read -r -p ""
				fi
				${ove_cmd2pathname["flock"]:?} -u ${fd}
				return 1
			fi

			if ${ove_cmd2pathname["grep"]:?} -q "Failed to watch" ${f_stderr}; then
				if [ -s "${f_stderr}" ]; then
					${ove_cmd2pathname["cat"]:?} ${f_stderr}
				fi
				ove_echo_error_noprefix "inotifywait did not established watches"
				if ove_sanity_check_tmux 2> /dev/null; then
					read -r -p ""
				fi
				${ove_cmd2pathname["flock"]:?} -u ${fd}
				return 1
			fi

			# still running?
			if ! kill -0 ${inotifywait_pid} > /dev/null 2>&1; then
				${ove_cmd2pathname["flock"]:?} -u ${fd}
				return 1
			fi
		fi

		# run the command
		OVE_PAGER="${ove_cmd2pathname["tee"]:?} /dev/null" ove-${1} "${@:2}"

		if [ ${use_inotify} -eq 1 ]; then
			# first iteration?
			if [ ${i} -eq 1 ]; then
				${ove_cmd2pathname["sleep"]:?} 1
				kill -9 ${inotifywait_pid} &> /dev/null
				wait &> /dev/null
				${ove_cmd2pathname["rm"]:?} ${all_files}

				# remove doublets and only regular files
				for f in $(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u ${files_modified_by_command}); do
					if [ -f ${f} ]; then
						echo ${f}
					fi
				done > ${files_modified_by_command}.uniq
				${ove_cmd2pathname["rm"]:?} ${files_modified_by_command}
				if [ $(${ove_cmd2pathname["wc"]:?} -l < ${files_modified_by_command}.uniq) -eq 0 ]; then
					use_inotify=0
					echo "no files accessed, not using inotify"
				fi

				# sleep before relasing lock
				${ove_cmd2pathname["sleep"]:?} 1

				# release lock
				${ove_cmd2pathname["flock"]:?} -u ${fd}
			fi

			# inotify was disabled above?
			if [ ${use_inotify} -eq 1 ]; then
				# allow user to change the file watch list
				echo
				if [ ${i} -lt 3 ]; then
					echo "press 'm' to modify the file watch list (=$(${ove_cmd2pathname["wc"]:?} -l < ${files_modified_by_command}.uniq) files)"
				fi
				read -n 1 -s -r -t 0.1
				if [[ ${REPLY} =~ ^[Mm]$ ]]; then
					echo "file watch list: ${files_modified_by_command}.uniq"
					while true; do
						read -n 1 -s -r -p "press 'p' to proceeed (time-out in 1 min)" -t 60
						if [ ${?} -gt 128 ]; then
							break
						fi
						if [[ ${REPLY} =~ ^[Pp]$ ]]; then
							${ove_cmd2pathname["sync"]:?} ${files_modified_by_command}.uniq
							while read -r line; do
								if [ -e ${line} ]; then
									continue
								fi
								echo
								echo "'${line}' does not exist, try again"
								continue 2
							done <${files_modified_by_command}.uniq
							break
						fi
					done
					if [ $(${ove_cmd2pathname["wc"]:?} -l <${files_modified_by_command}.uniq) -eq 0 ]; then
						echo
						ove_echo_error_noprefix "no files to watch, disable inotify"
						use_inotify=0
						if ove_sanity_check_tmux 2> /dev/null; then
							read -r -p ""
						fi
						continue
					fi
				fi

				echo
			fi
		fi

		echo -
		if [ ${use_inotify} -eq 1 ]; then
			s=${SECONDS}

			# sanity check that files exist
			# filenames sent to inotifywait (--fromfile) that begin with @ are excluded
			i=0
			j=
			s=
			while read -r line; do
				((i++))
				if [[ "$line" == @* ]] && [ -e "${line:1}" ]; then
					# masked and file exists => unmask
					s+=" $i"
				elif [[ "$line" == @* ]] && [ ! -e "${line:1}" ]; then
					# masked and file still does not exit => do nothing
					true
				elif [ ! -e "${line}" ]; then
					# not masked and file still does not exit => mask it
					j+=" $i"
				fi
			done <${files_modified_by_command}.uniq

			# mask files
			if [ "$j" != "" ]; then
				sed_expr=
				for i in $j; do
					sed_expr+=" -e '${i}s,^,@,'"
				done
				eval ${ove_cmd2pathname["sed"]:?} -i $sed_expr ${files_modified_by_command}.uniq
			fi

			# unmask files
			if [ "$s" != "" ]; then
				sed_expr=
				for i in $s; do
					sed_expr+=" -e '${i}s,^.,,'"
				done
				eval ${ove_cmd2pathname["sed"]:?} -i $sed_expr ${files_modified_by_command}.uniq
			fi

			if ! ove_inotifywait ${_timeout} ${files_modified_by_command}.uniq; then
				ove_echo_error_noprefix "inotifywait failed"
				echo
				read -r -p "press ENTER to proceed (time-out in 30 sec) " -t 30
				continue
			fi

			# first iteration and if inotify returned within 3 seconds? sleep at least 3 secs
			if [ ${i} -eq 1 ] && [ $((SECONDS - s)) -lt 3 ]; then
				${ove_cmd2pathname["sleep"]:?} $((RANDOM%3 + 3))
			fi
		else
			if [ "${_timeout}" != "0" ]; then
				read_args="-t ${_timeout}"
			fi
			# shellcheck disable=SC2229
			read -n 1 -s -r -p '' ${read_args}
			if [[ ${REPLY} =~ ^[Qq]$ ]]; then
				break
			fi
		fi
	done
}

# ide:[close|reopen]:launch one or more 'loop'-commands specified by OVE_IDE_LOOP_ARGS (tmux only):UTIL
function ove-ide {
	ove_entry || return

	local i
	local line
	local loop_args

	if [ $# -gt 1 ] || ! ove_sanity_check_tmux; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 1 ]; then
		if [ "$1" = "close" ]; then
			ove-loop-close
			return 0
		elif [ "$1" = "reopen" ]; then
			ove-loop-close
			ove-ide
			return 0
		fi
		ove_command_usage
		return 1
	fi

	if [ "${OVE_IDE_LOOP_ARGS}" = "" ]; then
		ove_echo_error_noprefix "'OVE_IDE_LOOP_ARGS' is empty or not set"
		ove_command_usage
		return 1
	fi

	mapfile -t loop_args <<<"$(echo -e "${OVE_IDE_LOOP_ARGS//;/\\n}")"
	i=0
	while ((i < ${#loop_args[@]})); do
		ove-loop ${loop_args[i]}
		(( i+=1 ))
		${ove_cmd2pathname["sleep"]:?} ${OVE_IDE_SLEEP_BETWEEN_COMMANDS:=0.5}
	done
}

# run-parallel:t0 c0 [t1 c1 t2 c2...]:run commands in parallel (tmux only):UTIL
function ove-run-parallel {
	ove_entry || return

	local n=$#
	local t

	if [ $# -eq 0 ] || [ $((n%2)) -ne 0 ] || ! ove_sanity_check_tmux; then
		ove_command_usage
		return 1
	fi

	while true; do
		t=$1
		shift
		ove-run ${t} "${@:1:1}"
		shift
		if [ $# -eq 0 ]; then
			break
		fi
	done
}

function ove_validate_int_float {
	if ! [[ "${1}" =~ ^[0-9.,]+$ ]]; then
		return 1
	elif [[ "${1}" =~ [.,][0-9]+$ ]]; then
		# shellcheck disable=SC2001
		read -r -t $(${ove_cmd2pathname["sed"]:?} -e 's|[0-9]\+\([,.]\)[0-9]\+|\101|g' -e 's|\([,.]\)[0-9]\+|\101|g' <<<"${1}") 2> /dev/null
		if [ $? -lt 128 ]; then
			return 1
		fi
	fi

	return 0
}

# run:|t c:run one command 'c' in terminal/tmux with timeout 't' (0=no timeout):UTIL
function ove-run {
	ove_entry || return

	local _cmd
	local cmd
	local header
	local num_panes
	local read_args
	local _timeout
	local target_window
	local tmux_cmd
	local tmux_opt

	if [ $# -eq 1 ]; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 0 ]; then
		read -r -p "command timeout in sec (default 0 = no timeout): "
		if [ "${REPLY}" = "" ]; then
			_timeout=0
		else
			_timeout=${REPLY}
		fi
		read -r -p "command: "
		if [ "${REPLY}" = "" ]; then
			return
		else
			cmd=${REPLY}
		fi
	else
		_timeout=$1
		shift
		cmd=$*
	fi

	if ! ove_validate_int_float "${_timeout}"; then
		ove_command_usage
		echo "error: format issues '${_timeout}'" 1>&2
		return 1
	fi

	# turn off monitor mode to get rid of "Done" messages
	set +m
	if [ "${_timeout}" != "0" ]; then
		read_args="-t ${_timeout}"
	fi

	if ove_sanity_check_tmux 2> /dev/null; then
		if [ "${OVE_TMUX_PANE_HEADER}" = "wide" ]; then
			header="ove_echo_cyan_error ${OVE_OWEL_NAME}:${cmd} [t:${_timeout}]"
		elif [ "${OVE_TMUX_PANE_HEADER}" = "short" ]; then
			header="ove_echo_cyan_error_noprefix $(${ove_cmd2pathname["date"]:?} '+%Y-%m-%d %H:%M:%S'):${cmd}"
		elif [ "${OVE_TMUX_PANE_HEADER}" = "off" ]; then
			header="true"
		fi

		tmux_cmd="split-window"
		tmux_opt="-h"
		target_window=
		if ! [[ "${OVE_TMUX_PANE_PER_WINDOW}" =~ ^[0-9]+$ ]]; then
			ove_echo_warning_noprefix "invalid value for OVE_TMUX_PANE_PER_WINDOW: $OVE_TMUX_PANE_PER_WINDOW"
		elif [ ${OVE_TMUX_PANE_PER_WINDOW} -gt 0 ]; then
			num_panes=$(${ove_cmd2pathname["tmux"]:?} list-panes | ${ove_cmd2pathname["wc"]:?} -l)
			if [ $num_panes -ge ${OVE_TMUX_PANE_PER_WINDOW} ]; then
				if [ -s "${OVE_OWEL_STATE_DIR}/tmux-target-name" ]; then
					target_window=$(${ove_cmd2pathname["cat"]:?} "${OVE_OWEL_STATE_DIR}/tmux-target-name")
					if ${ove_cmd2pathname["tmux"]:?} list-panes -F'#W' -a | ${ove_cmd2pathname["grep"]:?} -q "$target_window"; then
						tmux_opt+=" -t ${target_window}"
						num_panes=$(${ove_cmd2pathname["tmux"]:?} list-panes -t ${target_window} | ${ove_cmd2pathname["wc"]:?} -l)
					else
						${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_STATE_DIR}/tmux-target-name
						target_window=
					fi
				fi

				if [ $num_panes -ge ${OVE_TMUX_PANE_PER_WINDOW} ]; then
					target_name="ove-${RANDOM}"
					if ${ove_cmd2pathname["tmux"]:?} list-panes -F'#W' -a | ${ove_cmd2pathname["grep"]:?} -q "$target_name"; then
						target_name+="-${RANDOM}"
					fi
					tmux_cmd="new-window"
					tmux_opt="-d -n $target_name"
					echo "$target_name" > ${OVE_OWEL_STATE_DIR}/tmux-target-name
				else
					tmux_opt+=" -d"
				fi
			fi
		fi

		${ove_cmd2pathname["tmux"]:?} $tmux_cmd $tmux_opt "\
			source ${OVE_BASE_DIR}/ove; \
			ove_init; \
			${header}; \
			OVE_PAGER='${ove_cmd2pathname[tee]:?} /dev/null' ${cmd}; \
			echo -; \
			read -n 1 -s -r -p '' ${read_args}"

		tmux_opt=
		if [ "$target_window" != "" ]; then
			tmux_opt="-t ${target_window}"
		fi
		${ove_cmd2pathname["tmux"]:?} select-layout ${tmux_opt} ${OVE_TMUX_LAYOUT}
		if [ "$target_window" = "" ]; then
			${ove_cmd2pathname["tmux"]:?} select-pane -t ${TMUX_PANE}
		fi
	else
		ove_echo_cyan_error "${cmd}"
		OVE_PAGER="${ove_cmd2pathname[tee]:?} /dev/null" ${cmd}
		echo -
		# shellcheck disable=SC2229
		read -n 1 -s -r -p '' ${read_args}
	fi

	# turn on monitor mode
	set -m
}

# kill processes
#
# $1   : 0 = prefix 'kill' with 'sudo'
#      : 1 = kill as user
# $2   : duration between signal
# $3...: pids...
function ove_kill_procs {
	local n
	local pid
	local prefix
	local sig

	if [ $# -lt 3 ]; then
		return 1
	fi

	if [ $1 -eq 0 ] && [ ${EUID} -ne 0 ]; then
		prefix="${ove_cmd2pathname["sudo"]:?}"
	fi

	n="$2"
	shift 2
	pids="$*"

	for pid in "$@"; do
		if [ $pid -eq $BASHPID ]; then
			continue
		elif ${prefix} kill -0 ${pid} > /dev/null 2>&1; then
			for sig in SIGTERM SIGINT SIGKILL; do
				${prefix} kill -${sig} ${pid} 2> /dev/null
				${ove_cmd2pathname["sleep"]:?} ${n}
				if ! ${prefix} kill -0 ${pid} 2> /dev/null; then
					break
				fi
			done
		fi
	done
}

# loop-close: :close all 'loop'-panes (tmux only):UTIL
function ove-loop-close {
	ove_entry || return

	if [ $# -gt 0 ] || ! ove_sanity_check_tmux; then
		ove_command_usage
		return 1
	fi

	ove_kill_procs 1 0.2 $(${ove_cmd2pathname["pgrep"]:?} -f ove_loop_command)
	ove_kill_procs 1 0.2 $(${ove_cmd2pathname["pgrep"]:?} -f "inotifywait.*${OVE_OWEL_TMP_DIR}")
}

# loop:|[timeout|x] [inotify|x] [max-count|x] command]:loop one OVE command:UTIL
function ove-loop {
	ove_entry || return

	local _cmd
	local cmd
	local max_count
	local _timeout
	local use_inotify

	if [ $# -gt 0 ] && [ $# -lt 4 ]; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 0 ]; then
		read -r -p "command timeout in sec (default 0 = no timeout): "
		if [ "${REPLY}" = "" ]; then
			_timeout=0
		else
			_timeout=${REPLY}
		fi
		read -r -p "inotify 0=no 1=yes (default 0): "
		if [ "${REPLY}" = "" ]; then
			use_inotify=0
		else
			use_inotify=${REPLY}
		fi
		read -r -p "max count: (default 0 = forever): "
		if [ "${REPLY}" = "" ]; then
			max_count=0
		else
			max_count=${REPLY}
		fi
		read -r -p "command: "
		if [ "${REPLY}" = "" ]; then
			return
		else
			cmd=${REPLY}
		fi
	else
		if [ "${1,}" = "x" ]; then
			read -r -p "command timeout in sec (0=no timeout): "
			if [ "${REPLY}" = "" ]; then
				_timeout=0
			else
				_timeout=${REPLY}
			fi
		else
			_timeout=$1
		fi

		if [ "${2,}" = "x" ]; then
			read -r -p "inotify 0=no 1=yes (default 0): "
			if [ "${REPLY}" = "" ]; then
				use_inotify=0
			else
				use_inotify=${REPLY}
			fi
		else
			use_inotify=$2
		fi

		if [ "${3,}" = "x" ]; then
			read -r -p "max count: (default 0 = forever): "
			if [ "${REPLY}" = "" ]; then
				max_count=0
			else
				max_count=${REPLY}
			fi
		else
			max_count=$3
		fi

		shift 3
		cmd=$*
	fi

	if ! ove_validate_int_float "${_timeout}"; then
		ove_command_usage
		echo "error: format issues '${_timeout}'" 1>&2
		return 1
	fi

	if ! [[ "${use_inotify}" =~ ^[0-1]$ ]]; then
		echo "error: inotify: 0 or 1" 1>&2
		ove_command_usage
		return 1
	fi

	if [ "${use_inotify}" -eq 1 ] && ! ove_check_command "inotifywait"; then
		return 1
	fi

	if ! [[ "${max_count}" =~ ^[0-9]+$ ]]; then
		echo "error: max count: just numbers" 1>&2
		ove_command_usage
		return 1
	fi

	cmd=${cmd#ove }
	cmd=${cmd#ove-}
	_cmd=$(${ove_cmd2pathname["cut"]:?} -d' ' -f1 <<<"${cmd}")
	if [ "$(type -t ove-"${_cmd}")" != "function" ]; then
		ove_echo_error_noprefix "'${_cmd}' unknown command"
		return 1
	fi

	if ove_sanity_check_tmux 2> /dev/null; then
		${ove_cmd2pathname["tmux"]:?} split-window -h "\
			source ${OVE_BASE_DIR}/ove; \
			ove_init; \
			ove_loop_command ${_timeout} ${use_inotify} ${max_count} '${cmd}'"

		${ove_cmd2pathname["tmux"]:?} select-layout ${OVE_TMUX_LAYOUT}
		${ove_cmd2pathname["tmux"]:?} select-pane -t 0
	else
		ove_loop_command ${_timeout} ${use_inotify} ${max_count} "${cmd}"
	fi
}

function ove_sanitise_vars {
	local corrupt

	# corrupt OVE_LOGLEVEL?
	if [ -n "${OVE_LOGLEVEL}" ]; then
		corrupt=0
		if ! [ "${OVE_LOGLEVEL}" -eq "${OVE_LOGLEVEL}" ] 2> /dev/null; then
			corrupt=1
		elif ! [[ "${OVE_LOGLEVEL}" =~ ^[0-9]+$ ]]; then
			corrupt=1
		fi

		if [ ${corrupt} -eq 1 ]; then
			ove-loglevel 1 > /dev/null
		fi
	fi

	return 0
}

function ove_trace_setup {
	local strace_expression

	if [ ${OVE_LOGLEVEL} -lt 3 ]; then
		unset OVE_TRACE_CMD
		return 0
	fi

	if [ -e ${OVE_OWEL_TMP_DIR}/trace-${cmd} ]; then
		${ove_cmd2pathname["rm"]:?} -rf ${OVE_OWEL_TMP_DIR}/trace-${cmd}
	fi
	${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_TMP_DIR}/trace-${cmd}

	if [ ${OVE_LOGLEVEL} -eq 5 ]; then
		strace_expression="connect,bind,execve"
	elif [ ${OVE_LOGLEVEL} -eq 6 ]; then
		strace_expression="network,process"
	elif [ ${OVE_LOGLEVEL} -ge 7 ] || [ ${OVE_LOGLEVEL} -lt 10 ]; then
		strace_expression="file"
	else
		strace_expression="execve"
	fi

	OVE_TRACE_CMD="strace "
	OVE_TRACE_CMD+="-s 1024 "
	OVE_TRACE_CMD+="-q "
	OVE_TRACE_CMD+="-o ${OVE_OWEL_TMP_DIR}/trace-${cmd}/trace-${cmd} "
	OVE_TRACE_CMD+="-ff "
	OVE_TRACE_CMD+="-T "
	if [ ${OVE_LOGLEVEL} -ne 10 ]; then
		OVE_TRACE_CMD+="-e ${strace_expression} "
	fi
	OVE_TRACE_CMD+="-ttt "
	if [ ${OVE_LOGLEVEL} -eq 8 ]; then
		OVE_TRACE_CMD+="-z "
	elif [ ${OVE_LOGLEVEL} -eq 9 ]; then
		OVE_TRACE_CMD+="-Z "
	fi
	export OVE_TRACE_CMD
	if [ -e ${OVE_OWEL_TMP_DIR}/bash.pid ]; then
		${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/bash.pid
	fi
	if [ -e ${OVE_OWEL_TMP_DIR}/trace.pid ]; then
		${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/trace.pid
	fi
	if [ -e ${OVE_OWEL_TMP_DIR}/trace.cont ]; then
		${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/trace.cont
	fi

	{
		local s=${SECONDS}

		while true; do
			if [ -e ${OVE_OWEL_TMP_DIR}/bash.pid ]; then
				break
			fi

			if [ $((SECONDS - s)) -gt 5 ]; then
				break
			fi
		done

		if [ ! -e ${OVE_OWEL_TMP_DIR}/bash.pid ]; then
			exit 1
		fi

		# launch trace in background and let it start up
		(${OVE_TRACE_CMD} -p $(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/bash.pid) & echo $! > ${OVE_OWEL_TMP_DIR}/trace.pid)
		${ove_cmd2pathname["sleep"]:?} 1
		if [ -s ${OVE_OWEL_TMP_DIR}/trace.pid ] && \
			! kill -0 $(cat ${OVE_OWEL_TMP_DIR}/trace.pid) 2> /dev/null; then
			echo "0" > ${OVE_OWEL_TMP_DIR}/trace.cont
		else
			echo "1" > ${OVE_OWEL_TMP_DIR}/trace.cont
		fi
	} &
}

function ove_trace_cleanup {
	local f

	for f in bash.pid trace.cont trace.pid; do
		if [ -e "${OVE_OWEL_TMP_DIR}/${f}" ]; then
			${ove_cmd2pathname["rm"]:?} "${OVE_OWEL_TMP_DIR}/${f}"
		fi
	done
}

function ove_trace_post {
	local pid

	if [ -n "${OVE_TRACE_CMD+x}" ]; then
		if [ ! -e ${OVE_OWEL_TMP_DIR}/trace.pid ]; then
			pid=0
		else
			pid=$(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/trace.pid)
			ove_kill_procs 1 1 ${pid}
		fi

		ove_trace_cleanup

		if [ $pid -ne 0 ]; then
			{
				if [ ${OVE_LOGLEVEL} -eq 10 ]; then
					ove_analyze_strace_raw ${OVE_OWEL_TMP_DIR}/trace-${cmd}
				elif [ ${OVE_LOGLEVEL} -eq 3 ] || [ ${OVE_LOGLEVEL} -eq 4 ]; then
					ove_analyze_strace_execve_timing ${OVE_OWEL_TMP_DIR}/trace-${cmd}
				elif [ ${OVE_LOGLEVEL} -eq 5 ]; then
					ove_analyze_strace_connect ${OVE_OWEL_TMP_DIR}/trace-${cmd}
				elif [ ${OVE_LOGLEVEL} -eq 6 ]; then
					ove_strace_create_graph ${OVE_OWEL_TMP_DIR}/trace-${cmd} ${cmd}
				elif [ ${OVE_LOGLEVEL} -ge 7 ] || [ ${OVE_LOGLEVEL} -lt 10 ]; then
					ove_analyze_strace_file ${OVE_OWEL_TMP_DIR}/trace-${cmd}
				fi
			} | ${ove_cmd2pathname["tee"]:?} -a ${OVE_LAST_COMMAND}
		fi

		unset OVE_TRACE_CMD
	fi
}

function ove_batch_helper {
	local a
	local f
	local h
	local id

	id="$1"

	# create a on finish script
	f="${OVE_GLOBAL_STATE_DIR}/ove-ts-onfinish"
	${ove_cmd2pathname["cat"]:?} > "${f}" << EOF
#!/usr/bin/env bash

# rename ts output to OVE_LAST_COMMAND
if [ -s \$3 ]; then
	\mv -v "\$3" \$OVE_LAST_COMMAND
fi

# cleanup onfinish files that contains an id
if [ "\$TS_ONFINISH" != "${f}" ]; then
	rm -v \$TS_ONFINISH
fi
EOF

	a=0
	# append any post hooks
	if [[ -v ove_hooks_post[${cmd}] ]]; then
		for h in ${ove_hooks_post[${cmd}]}; do
			if [ -s "$h" ] && [ -x "$h" ]; then
				if [ "${a}" -eq 0 ]; then
					a="${OVE_GLOBAL_STATE_DIR}/${id}-ove-ts-onfinish"
					if ! ${ove_cmd2pathname["cp"]:?} -a $f ${a}; then
						return 1
					fi
					f="${a}"
					a=1
				fi

				# append the hook
				if [ "$OVE_HOOKS_APPEND_TO_LASTLOG" = "1" ]; then
					echo "$h |& ${ove_cmd2pathname["tee"]:?} -a \$OVE_LAST_COMMAND" >> ${f}
				else
					echo "$h" >> ${f}
				fi
			fi
		done
	fi

	if [ ! -x "${f}" ]; then
		# make the script executable
		if ! ${ove_cmd2pathname["chmod"]:?} +x "${f}"; then
			return 1
		fi
	fi

	echo $f
}

function ove_rec_start {
	if ! ove_check_command "recordmydesktop"; then
		return 1
	elif ! ove_check_command "xdotool"; then
		return 1
	fi

	# already recording?
	if ${ove_cmd2pathname["pgrep"]:?} -f recordmydesktop > /dev/null; then
		rec_pid=0
		return 0
	fi

	# turn off monitor mode to get rid of "Done" messages
	set +m

	# start recording
	${ove_cmd2pathname["recordmydesktop"]:?} \
		--no-cursor \
		--no-frame \
		--no-sound \
		-o ${OVE_LAST_COMMAND/.log}.ogv \
		--windowid $(printf "0x%x\n" $(${ove_cmd2pathname["xdotool"]:?} getactivewindow)) \
		2> "${OVE_TMP}/rec.err" &
	rec_pid=$!

	# sanity check recording
	${ove_cmd2pathname["sleep"]:?} 1
	if ! kill -0 "${rec_pid}" 2> /dev/null; then
		set -m
		ove_echo_error_noprefix "recordmydesktop: $(${ove_cmd2pathname["cat"]:?} ${OVE_TMP}/rec.err)"
		return 1
	fi

	return 0
}

function ove_rec_stop {
	local i
	local o

	if [ "$rec_pid" -eq 0 ]; then
		return 0
	fi

	# turn off monitor mode to get rid of "Done" messages
	set +m

	${ove_cmd2pathname["sleep"]:?} 1

	# stop recording
	kill -SIGINT "${rec_pid}" 2> /dev/null

	# wait for recording
	while true; do
		if ! kill -0 "${rec_pid}" 2> /dev/null; then
			break
		fi
		${ove_cmd2pathname["sleep"]:?} 1
	done

	o="${OVE_LAST_COMMAND/.log}.ogv"

	# sanity check
	if [ ! -s "$o" ]; then
		ove_echo_error_noprefix "recordmydesktop: $(${ove_cmd2pathname["cat"]:?} ${OVE_TMP}/rec.err)"
		return
	fi

	if command -v ffmpeg > /dev/null; then
		i="${OVE_LAST_COMMAND/.log}.ogv"
		o="${OVE_LAST_COMMAND/.log}.mp4"

		# convert to MPEG-4
		if ! ${ove_cmd2pathname["ffmpeg"]:?} -i "${i}" "${o}" 2> /dev/null; then
			o="${OVE_LAST_COMMAND/.log}.ogv"
		else
			${ove_cmd2pathname["rm"]:?} "${i}"
		fi
	fi

	# display path and size
	${ove_cmd2pathname["du"]:?} -sh "${o}" 1>&2

	# turn on monitor mode
	set -m
}

function ove {
	local candidates
	local cmd
	local cmd_and_args
	local h
	local id
	local log_cmd
	local on_finish
	local re
	local rec_pid
	local ret

	cmd="$1"

	# keep this as early as possible
	if [ "${cmd}" = "cd" ] \
		|| [ "${cmd}" = "init" ] \
		|| [ "${cmd}" = "l" ] \
		|| [ "${cmd}" = "lr" ] \
		|| [ "${cmd}" = "ps" ] \
		|| [ "${cmd}" = "oneliner" ]; then
		ove-${cmd} "${@:2}"
		return $?
	fi

	# sanity check
	if ! ove_get_base_dir > /dev/null; then
		return 1
	fi

	# clean up any trace leftovers
	ove_trace_cleanup

	# fix broken vars
	ove_sanitise_vars

	if ! ove_verify_checksums && ! ove_reinit; then
		return 1
	fi

	ove_update_terminal_stats

	if [ $# -eq 0 ]; then
		ove-help | ${OVE_PAGER}
		return 0
	elif [ "$(type -t ove-"${cmd}")" != "function" ]; then
		re=\\b${cmd}
		if ! [[ "${OVE_ALL_COMMANDS}" =~ ${re} ]]; then
			ove_echo_error_noprefix "'${cmd}' unknown command"
			return 1
		fi

		candidates=$(ove-list-commands ^${cmd} | \
			${ove_cmd2pathname["grep"]:?} -E -v "^cmd|^---")
		if [ "${candidates}" != "" ] && \
			[ ${OVE_AUTO_CORRECT} -eq 1 ] && \
			[ $(${ove_cmd2pathname["wc"]:?} -l <<<"${candidates}") -eq 1 ]; then
			cmd=$(${ove_cmd2pathname["tail"]:?} -1 <<<"${candidates}")
			cmd=${cmd%% *}
			ove ${cmd} "${@:2}"
			return $?
		fi

		ove_echo_error_noprefix "'${cmd}' unknown command"
		if [ "${candidates}" != "" ]; then
			echo
			echo "Did you mean?"
			echo "${candidates}"
		fi

		return 1
	fi

	if [ ${EUID} -eq 0 ]; then
		cmd_and_args="# ove ${cmd}"
	else
		cmd_and_args="$ ove ${cmd}"
	fi

	if [ $# -gt 1 ]; then
		cmd_and_args+=" ${*:2}"
	fi

	if [ -n "${OVE_LOCAL_ECHO+x}" ]; then
		if [ "${OVE_LOCAL_ECHO}" -eq 1 ]; then
			echo "${cmd_and_args}" 1>&2
		elif [ "${OVE_LOCAL_ECHO}" -eq 2 ]; then
			ove_echo_cyan_noprefix "${cmd_and_args}" 1>&2
		fi
	fi

	# do not log commands that:
	# * affect the user's shell
	# * 'complex' commands (e.g. vi/emacs)
	if [ "${cmd}" = "add-config" ] || \
		[ "${cmd}" = "config" ] || \
		[ "${cmd}" = "checkout" ] || \
		[ "${cmd}" = "dry-run" ] || \
		[ "${cmd}" = "echo" ] || \
		[ "${cmd}" = "emacs" ] || \
		[ "${cmd}" = "gvim" ] || \
		[ "${cmd}" = "lastlog" ] || \
		[ "${cmd}" = "lastlog-replay" ] || \
		[ "${cmd}" = "lastlog-summary" ] || \
		[ "${cmd}" = "less-lastlog" ] || \
		[ "${cmd}" = "loglevel" ] || \
		[ "${cmd}" = "rec" ] || \
		[ "${cmd}" = "revtab-check" ] || \
		[ "${cmd}" = "tail-lastlog" ] || \
		[ "${cmd}" = "ts" ] || \
		[ "${cmd}" = "unsource" ] || \
		[ "${cmd}" = "update-revtab" ] || \
		[ "${cmd}" = "vi" ]; then
		ove-${cmd} "${@:2}"
		return $?
	fi

	# setup log file
	${ove_cmd2pathname["mkdir"]:?} -p ${OVE_LOG_DIR}/${OVE_SHA}
	(cd ${OVE_LOG_DIR} && ${ove_cmd2pathname["ln"]:?} -sfn ${OVE_SHA} current)
	id=$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S%N')
	OVE_LAST_COMMAND="${OVE_LOG_DIR}/${OVE_SHA}/${id}-ove-${cmd}-${HOSTNAME}-${OVE_OWEL_NAME}.log"

	# terminals and parallel project commands use 'script', everything else use 'tee'
	log_cmd="tee"
	if [ -t 1 ]; then
		log_cmd="script"
	elif [[ ${cmd} = *-parallel ]]; then
		re=\\b${cmd/-parallel/}\\b
		if [[ "${OVE_PROJECT_COMMANDS} buildme" =~ ${re} ]]; then
			log_cmd="script"
		fi
	fi

	# batch the command?
	if [ "$OVE_BATCH_IT" != "0" ]; then
		log_cmd="tsp"
		if ! ove_check_command "tsp"; then
			return 1
		elif ! on_finish=$(ove_batch_helper $id); then
			return 1
		fi

		OVE_BATCH_IT=0
	fi

	if [ "$OVE_RECORD_IT" != "0" ]; then
		if ! ove_rec_start; then
			return 1
		fi
	fi

	# pre hooks?
	if [[ -v ove_hooks_pre[${cmd}] ]]; then
		for h in ${ove_hooks_pre[${cmd}]}; do
			if [ -s "$h" ] && [ -x "$h" ]; then
				if [ "$OVE_HOOKS_APPEND_TO_LASTLOG" = "1" ]; then
					$h "${@:2}" |& ${ove_cmd2pathname["tee"]:?} -a ${OVE_LAST_COMMAND}
					ret=${PIPESTATUS[0]}
				else
					$h "${@:2}"
					ret=$?
				fi

				if [ $ret -ne 0 ]; then
					ove_echo_error_noprefix "pre hook '$h' failed with exit code $ret"
					return $ret
				fi
			fi
		done
	fi

	# do not create the 'ongo' symlink for tsp
	if [ "${log_cmd}" != "tsp" ]; then
		${ove_cmd2pathname["ln"]:?} -s -f ${OVE_LAST_COMMAND} ${OVE_LOG_DIR}/ongo
	fi

	if [ "${log_cmd}" = "script" ]; then
		# trace hook
		if ! ove_trace_setup; then
			return 1
		fi

		# turn off monitor mode to get rid of "Done" messages
		set +m

		# run the command
		if [[ "${OVE_OS_KERNEL,,}" == *linux* ]]; then
			SHELL=${ove_cmd2pathname["bash"]:?} \
				${ove_cmd2pathname["script"]:?} ${OVE_SCRIPT_OPTIONS} \
				-t${OVE_LAST_COMMAND/.log}.timing \
				-c "source ${OVE_BASE_DIR}/ove || exit 1; OVE_LAST_COMMAND=$OVE_LAST_COMMAND; ove-${cmd}$([ $# -gt 1 ] && printf -- ' "%s"' "${@:2}")" \
				${OVE_LAST_COMMAND}
		else
			SHELL=${ove_cmd2pathname["bash"]:?} \
				${ove_cmd2pathname["script"]:?} ${OVE_SCRIPT_OPTIONS} \
				${OVE_LAST_COMMAND} \
				bash -c "source ${OVE_BASE_DIR}/ove || exit 1; OVE_LAST_COMMAND=$OVE_LAST_COMMAND; ove-${cmd}$([ $# -gt 1 ] && printf -- ' "%s"' "${@:2}")"
		fi
		ret=$?

		# trace post hook
		ove_trace_post

		if [[ "${OVE_OS_KERNEL,,}" == *linux* ]]; then
			# remove NULL bytes and insert command+args at line 2
			${ove_cmd2pathname["sed"]:?} -i -e 's/\x0//' -e "2i${cmd_and_args}\r" ${OVE_LAST_COMMAND}

			# compensate timing file for command, args and linefeed
			${ove_cmd2pathname["sed"]:?} -i -e "1i0.1 $((${#cmd_and_args}+1))" ${OVE_LAST_COMMAND/.log}.timing
		fi

		# turn on monitor mode
		set -m
	elif [ "${log_cmd}" = "tsp" ]; then
		# run the command using Task Spooler
		TS_SOCKET=$OVE_TMP/ts-socket.$EUID \
			TS_ONFINISH="${on_finish}" \
			${ove_cmd2pathname["tsp"]:?} \
			${ove_cmd2pathname["bash"]:?} \
			-c "source ${OVE_BASE_DIR}/ove; OVE_LAST_COMMAND=$OVE_LAST_COMMAND; ove-${cmd}$([ $# -gt 1 ] && printf -- ' "%s"' "${@:2}")"
	else
		# none-terminal => use tee

		if command -v setsid > /dev/null && [ "$OVE_COMMAND_SETSID" -eq 1 ]; then
			# we have 'setsid' AND we want to run the command in a separate session
			${ove_cmd2pathname["setsid"]:?} \
				-w \
				${ove_cmd2pathname["bash"]:?} \
				-c "ove-${cmd} ${*:2}" 2>&1 | ${ove_cmd2pathname["tee"]:?} -a -i ${OVE_LAST_COMMAND}
		else
			{
				ove-${cmd} "${@:2}"
			} 2>&1 | ${ove_cmd2pathname["tee"]:?} -a -i ${OVE_LAST_COMMAND}
		fi
		ret=${PIPESTATUS[0]}

		# remove NULL bytes AND insert command, args and exit code at line 1
		if [ -s "${OVE_LAST_COMMAND}" ]; then
			${ove_cmd2pathname["sed"]:?} -i -e 's/\x0//g' -e "1i${cmd_and_args} # exit code: ${ret}" ${OVE_LAST_COMMAND}
		else
			echo "${cmd_and_args} # exit code: ${ret}" > ${OVE_LAST_COMMAND}
		fi
	fi

	if [ "${log_cmd}" != "tsp" ]; then
		if [ -n "${OVE_ANONYMIZE_LOGS+x}" ] && [ "${OVE_ANONYMIZE_LOGS}" -eq 1 ]; then
			${ove_cmd2pathname["sed"]:?} -i \
				-e "s,$OVE_BASE_DIR,\$OVE_BASE_DIR,g" \
				-e "s,$OVE_USER,\$OVE_USER,g" \
				-e "s,$HOSTNAME,\$HOSTNAME,g" ${OVE_LAST_COMMAND}
		fi

		${ove_cmd2pathname["ln"]:?} -s -f ${OVE_LAST_COMMAND} ${OVE_LOG_DIR}/last
	fi

	# auto remove old logs?
	if [ -n "${OVE_AUTO_RM_LOGS+x}" ] && [ ${OVE_AUTO_RM_LOGS} -gt 0 ] && [ "${cmd}" != "rm-logs" ]; then
		ove-rm-logs ${OVE_AUTO_RM_LOGS} y
	fi

	# post hooks?
	if [ "${log_cmd}" != "tsp" ] && [[ -v ove_hooks_post[${cmd}] ]]; then
		for h in ${ove_hooks_post[${cmd}]}; do
			if [ -s "$h" ] && [ -x "$h" ]; then
				if [ "$OVE_HOOKS_APPEND_TO_LASTLOG" = "1" ]; then
					$h "${@:2}" |& ${ove_cmd2pathname["tee"]:?} -a ${OVE_LAST_COMMAND}
					ret=${PIPESTATUS[0]}
				else
					$h "${@:2}"
					ret=$?
				fi

				if [ $ret -ne 0 ]; then
					ove_echo_error_noprefix "post hook '$h' failed with exit code $ret"
					return $ret
				fi
			fi
		done
	fi

	if [ "$OVE_RECORD_IT" != "0" ]; then
		ove_rec_stop
	fi

	return ${ret}
}

# task:[task args]:check task man pages, taskwarrior [duckduckgo.com/?q=taskwarrior]:UTIL
function ove-task {
	ove_entry || return

	local ret

	if ! ove_check_command "task"; then
		return 1
	fi

	if [ ! -s $OVE_OWEL_DIR/.taskrc ]; then
		echo 'verbose=0' > $OVE_OWEL_DIR/.taskrc
	fi

	TASKDATA=$OVE_OWEL_DIR/.task \
		TASKRC=$OVE_OWEL_DIR/.taskrc \
		${ove_cmd2pathname["task"]:?} "$@"
}

# ts:[ts/tsp args]:check ts/tsp man pages:CORE
function ove-ts {
	ove_entry || return

	if ! ove_check_command "tsp"; then
		return 1
	fi

	if [ $# -eq 0 ]; then
		TS_SOCKET=$OVE_TMP/ts-socket.$EUID ${ove_cmd2pathname["tsp"]:?} | \
			${ove_cmd2pathname["sed"]:?} \
			-e '/^ID/d' \
			-e "s,${ove_cmd2pathname["bash"]:?}.*OVE_LAST_COMMAND=,,g" \
			-e 's,\([0-9]\+.*finished.*\)/tmp/ts-out\.[a-zA-Z0-9]\+.* \(/.*log\);,\1 \2,g' \
			-e "s,\(.*\)\($OVE_LOG_DIR/${OVE_SHA}/2.*.log\)\(.*\),\1\3@\2,g" | \
			${ove_cmd2pathname["column"]:?} -t -s@ | \
			${ove_cmd2pathname["tac"]:?}
	else
		TS_SOCKET=$OVE_TMP/ts-socket.$EUID \
			${ove_cmd2pathname["tsp"]:?} "$@"
	fi
}

# fzf:[loop]:OVE fzf [duckduckgo.com/?q=fzf]:UTIL
function ove-fzf {
	ove_entry || return

	local args
	local cmd
	local shell

	if ! ove_check_command "fzf"; then
		return 1
	elif ! ove_get_base_dir > /dev/null; then
		return 1
	elif [ $# -gt 1 ]; then
		ove_command_usage
		return 1
	fi

	shell=${ove_cmd2pathname["bash"]:?}
	while true; do
		# shellcheck disable=SC2016
		cmd=$(${ove_cmd2pathname["xargs"]:?} -n 1 <<<"${OVE_ALL_COMMANDS}" | \
			${ove_cmd2pathname["grep"]:?} -v '!' | \
			OVE_LOCAL_ECHO=0 SHELL=${shell} ${ove_cmd2pathname["fzf"]:?} \
			--cycle \
			--preview "ove-list-commands ^{1} | grep '^{1} '" \
			--preview-window=down:1 \
		)
		if [ "${cmd}" = "" ]; then
			break
		fi

		if ${ove_cmd2pathname["tr"]:?} ' ' '\n' <<<"${OVE_BUILT_INS_WITHOUT_ARGS:?}" | \
			${ove_cmd2pathname["grep"]:?} -q ^${cmd}$; then
			if [ "$1" = "loop" ]; then
				echo "$ ove-loop x x x ${cmd}"
				ove-loop x x x ${cmd}
				echo -
			else
				ove-run 0 "ove ${cmd}"
			fi
			continue
		fi

		COMP_WORDS=(ove "${cmd}" ' ')
		COMP_LINE="ove ${cmd}"
		COMP_CWORD=3
		COMP_POINT=${#COMP_LINE}
		ove_bash_complete
		if [ ${#COMPREPLY[@]} -eq 0 ]; then
			if [ $1 = "loop" ]; then
				echo "$ ove-loop x x x ${cmd}"
				ove-loop x x x ${cmd}
				echo -
			else
				ove-run 0 "ove ${cmd}"
			fi
		else
			args=$(printf '%s\n' "${COMPREPLY[@]}" | \
				LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u | \
				SHELL=${shell} ${ove_cmd2pathname["fzf"]:?} \
					--cycle \
					--preview "echo ESC\|CTRL+C to skip args $ ove ${cmd} {}" \
					--preview-window=down:1)

			if [ "$1" = "loop" ]; then
				echo "$ ove-loop x x x ${cmd} ${args}"
				ove-loop x x x ${cmd} ${args}
				echo -
			else
				ove-run 0 "ove ${cmd} ${args}"
			fi
		fi
	done
}

function ove_project_validate_name {
	if ! ove_read_config_validate_name "$1"; then
		return 1
	elif [ "$1" = "common" ]; then
		return 1
	else
		return 0
	fi
}

# not really a complete YAML parser
function ove_parse_yaml {
	local col
	local i
	local key
	local key_col
	local line
	local project
	local v
	local val
	local val_col

	i=0
	while IFS= read -r line; do
		((i++))
		if [ ${i} -eq 1 ] && [ "${line}" = "---" ]; then
			continue
		elif [ "${line}" = "---" ]; then
			echo "error: format error: document start at wrong position in '$1' at line #${i} '${line}'" 1>&2
			return 1
		elif [[ ${line:0:1} == \#* ]] || [[ ${line:0:1} == '' ]] || [[ ${line::2} == "//" ]]; then
			continue
		elif [ "${line:0:1}" != " " ]; then
			if [ "${line: -1}" != ":" ]; then
				echo "error: format error: project name should end with a colon in '$1' at line #${i} '${line}'" 1>&2
				return 1
			elif ! ove_project_validate_name ${line::-1}; then
				echo "error: format error: project name '${line::-1}' is not allowed at line #${i} '${line}'" 1>&2
				return 1
			fi
			project=${line::-1}
			unset keys
			declare -A keys
			col=1
		elif ! [[ ${line} =~ ^[[:space:]]+ ]]; then
			return 1
		elif ! col=${#BASH_REMATCH[0]}; then
			return 1
		elif [ "${line:$col:1}" = "#" ]; then
			continue
		elif [[ "${line}" == *": "* ]]; then
			echo "error: format error: colon followed by a space is not allowed in '$1' at line #${i} '${line}'" 1>&2
			return 1
		elif [ "${line: -1}" = ":" ]; then
			if [ "${key_col}" != "" ] && [ ${key_col} -ne ${col} ]; then
				echo "error: format error: a key at wrong place? in '$1' at line #${i} '${line}'" 1>&2
				return 1
			elif [ "$project" = "" ]; then
				echo "error: format error: a key without a project in '$1' at line #${i} '${line}'" 1>&2
				return 1
			fi

			key="${line//[[:blank:]]/}"
			key="${key::-1}"
			if ! ove_read_config_validate_name ${key}; then
				echo "error: format error: key name '${key}' is not allowed in '$1' at line #${i} '${line}'" 1>&2
				return 1
			elif  [ "${keys["${key}"]+isset}" ]; then
				echo "error: format error: duplicate key '${key}' in '$1' at line #${i} '${line}'" 1>&2
				return 1
			fi
			keys["${key}"]=1
			key_col=${col}
		elif [ "${key_col}" = "" ]; then
			echo "error: format error: no key found in '$1' at line #${i} '${line}'" 1>&2
			return 1
		elif [ ${col} -le ${key_col} ]; then
			echo "error: format error: weird indentation in '$1' at line #${i} '${line}'" 1>&2
			return 1
		elif [ "${val_col}" != "" ] && [ ${val_col} -ne ${col} ]; then
			echo "error: format error: check indentation in '$1' at line #${i} '${line}'" 1>&2
			return 1
		else
			if [ "${val_col}" = "" ]; then
				val_col=${col}
			fi
			val=${line#"${line%%[![:blank:]]*}"}
			for v in ${val}; do
				if [ -v ove_YaMl_${project}_${key} ]; then
					eval "ove_YaMl_${project}_${key}+=' ${v}'"
				else
					eval "ove_YaMl_${project}_${key}+='${v}'"
				fi
			done
		fi
	done < $1

	return $?
}

function ove_project_commands_list {
	local a

	if [ ! -d "${OVE_OWEL_DIR}/projects" ]; then
		return 0
	fi

	a=$(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u <(
		# for each valid project: look for executable files except files with hyphen-minus, underscore and number sign
		for f in $(cd ${OVE_OWEL_DIR}/projects && ${ove_cmd2pathname["find"]:?} -L ${OVE_PROJECT_LIST} -perm -u=x -type f \
			-not -name '*-*' \
			-not -name '*_*' \
			-not -name 'common' \
			-not -name '*#*' 2> /dev/null); do
			echo ${f##*/};
		done

		if [ -e "${OVE_OWEL_DIR}/projects/common" ]; then
			# for the common directory: include all files except pre/post files and files with hyphen-minus, underscore, number sign
			for f in $(cd ${OVE_OWEL_DIR}/projects && ${ove_cmd2pathname["find"]:?} -L common -type f \
				-not -name '*.pre' \
				-not -name '*.post' \
				-not -name '*-*' \
				-not -name '*_*' \
				-not -name '*#*' 2> /dev/null); do
				echo ${f##*/};
			done
		fi
		)
	)

	if [ "${a}" != "" ]; then
		echo ${a}
	fi
}

# $1: dir (optional)
function ove_list_tags_and_branches {
	local d

	if [ $# -eq 0 ]; then
		d=${OVE_OWEL_DIR}
	else
		d=$1
	fi

	if [ ! -d ${d} ]; then
		return
	fi

	(
	ove_repo_cmd "${d}" tag
	ove_repo_cmd "${d}" branch --no-color --all --list | \
		${ove_cmd2pathname["grep"]:?} -v HEAD | \
		${ove_cmd2pathname["tr"]:?} -d '*' | \
		${ove_cmd2pathname["xargs"]:?} | \
		${ove_cmd2pathname["tr"]:?} ' ' '\n'
	) | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -V
}

# iterate through projects
function ove_projects_init {
	local i
	local m
	local name
	local needs_distro_version_found
	local os_version
	local projects
	local tmp_var
	local t
	local v

	unset ove_projects_name
	unset ove_projects_deps
	unset ove_projects_path
	unset ove_projects_needs
	unset ove_projects_version
	unset ove_projects_name2index
	unset ove_projects_tags
	ove_number_of_projects=0

	if [ ! -s "${OVE_OWEL_DIR}/projs" ] || [ "${OVE_PROJECT_LIST}" = "" ]; then
		return
	fi

	if ! ove_parse_yaml "${OVE_OWEL_DIR}/projs"; then
		if command -v yamllint > /dev/null; then
			${ove_cmd2pathname["yamllint"]:?} "${OVE_OWEL_DIR}/projs"
		fi
		return 1
	fi

	declare -a -g ove_projects_name
	declare -a -g ove_projects_deps
	declare -a -g ove_projects_path
	declare -a -g ove_projects_needs
	declare -a -g ove_projects_version
	declare -A -g ove_projects_name2index
	declare -A -g ove_projects_tags

	# create ove-functions for all project commands
	for m in ${OVE_PROJECT_COMMANDS}; do
		eval "ove-${m}() {
			ove_entry || return

			local i
			local ove_plugin_helptext=\"${m}:[project...|tag...]:run the '${m}' step for all or individual projects:BUILD\"
			local p
			local proj_list

			if ! ove_build_pre \$*; then
				return 1
			fi

			# common .pre
			if [ -e \${OVE_OWEL_DIR}/projects/common/${m}.pre ]; then
				source \${OVE_OWEL_DIR}/projects/common/${m}.pre
			fi

			if [ \$# -eq 0 ]; then
				i=0
				while ((i < ove_number_of_projects)); do
					if ! ove_projects_cmd "\${ove_projects_name[\${i}]}" ${m}; then
						return 1
					fi
					(( i+=1 ))
				done
			else
				if ! proj_list=\$(ove_validate_project_list \"\$@\"); then
					return 1
				fi

				for p in \$proj_list; do
					if ! ove_projects_cmd \${p} ${m}; then
						return 1
					fi
				done
			fi

			# common .post
			if [ -e \${OVE_OWEL_DIR}/projects/common/${m}.post ]; then
				source \${OVE_OWEL_DIR}/projects/common/${m}.post
			fi
		}"
	done

	# create parallel ove-functions for all project commands
	for m in ${OVE_PROJECT_COMMANDS}; do
		eval "ove-${m}-parallel() {
			ove_entry || return

			local i
			local ove_plugin_helptext=\"${m}-parallel:[project...|tag...]:run the '${m}' step for all or individual projects (in parallel):BUILD\"
			local p
			local proj_list

			if ! ove_build_pre \$*; then
				return 1
			fi

			# common .pre
			if [ -e \${OVE_OWEL_DIR}/projects/common/${m}.pre ]; then
				source \${OVE_OWEL_DIR}/projects/common/${m}.pre
			fi

			if [ \$# -eq 0 ]; then
				i=0
				while ((i < ove_number_of_projects)); do
					{
						if ! ove_projects_cmd "\${ove_projects_name[\${i}]}" ${m}; then
							kill -USR1 \$\$
						fi
					} &
					(( i+=1 ))
				done
			else
				if ! proj_list=\$(ove_validate_project_list \"\$@\"); then
					return 1
				fi

				for p in \$proj_list; do
					{
						if ! ove_projects_cmd \${p} ${m}; then
							kill -USR1 \$\$
						fi
					} &
				done
			fi

			wait

			# common .post
			if [ -e \${OVE_OWEL_DIR}/projects/common/${m}.post ]; then
				source \${OVE_OWEL_DIR}/projects/common/${m}.post
			fi
		}"
	done

	# clean/distclean/xyzclean-me functions
	for m in ${OVE_PROJECT_COMMANDS}; do
		if [[ $m != *clean ]]; then
			continue
		fi

		eval "ove-${m}me() {
			ove_entry || return

			local ove_plugin_helptext=\"${m}me:[project...|tag...]:$m project(s) and their dependencies:BUILD\"
			local proj_list

			if ! ove_build_pre \$*; then
				return 1
			fi

			if [ \$# -eq 0 ]; then
				if ! ove-$m; then
					return 1
				fi
			else
				if ! proj_list=\$(ove_validate_project_list \"\$@\"); then
					return 1
				fi
				ove-$m \$(ove_get_build_list \${proj_list})
			fi
		}"
	done

	read -a projects -r <<<"${OVE_PROJECT_LIST}"
	ove_number_of_projects=${#projects[@]}

	# bash does not like variables with hyphen-minus and dots
	os_version="${OVE_OS_VER//[.-]/_}"
	# set projects deps|name|path|needs|version
	i=0
	while ((i < ove_number_of_projects)); do
		# name
		name=${projects[${i}]}
		ove_projects_name[i]=${name}
		unset ove_${name}

		# index
		ove_projects_name2index[${name}]=${i}

		# deps
		tmp_var="ove_YaMl_${name}_deps"
		ove_projects_deps[i]=${!tmp_var}
		unset ${tmp_var}

		# path
		tmp_var="ove_YaMl_${name}_path"
		if [[ "${!tmp_var}" == *"$"* ]]; then
			t=$(eval echo ${!tmp_var})
			if [ "${t}" = "" ]; then
				ove_projects_path[i]="${OVE_BASE_DIR}"
			else
				v="$(${ove_cmd2pathname["readlink"]:?} -f -- ${t})"
				if [ "${v}" = "" ]; then
					ove_projects_path[i]="${OVE_BASE_DIR}/${t}"
				else
					ove_projects_path[i]="${v}"
				fi
			fi
		elif [ "${!tmp_var:0:1}" = "/" ]; then
			ove_projects_path[i]="${!tmp_var}"
		else
			ove_projects_path[i]="${OVE_BASE_DIR}"
			if [ "${!tmp_var}" = "." ]; then
				true
			elif [ "${!tmp_var}" != "" ]; then
				ove_projects_path[i]+="/${!tmp_var}"
			fi
		fi
		unset ${tmp_var}

		# needs
		tmp_var="ove_YaMl_${name}_needs"
		ove_projects_needs[i]=$(eval echo ${!tmp_var})
		unset ${tmp_var}

		# tags
		tmp_var="ove_YaMl_${name}_tags"
		for t in ${!tmp_var};  do
			if [ "${ove_projects_tags[${t}]}" = "" ]; then
				ove_projects_tags[${t}]="${name}"
			else
				ove_projects_tags[${t}]+=" ${name}"
			fi
		done
		unset ${tmp_var}

		# distro needs
		needs_distro_version_found=0
		for m in ${OVE_OS_ID} ${OVE_OS_ID_LIKE}; do
			tmp_var="ove_YaMl_${name}_needs_${m//-/_}_${os_version}"
			if [ "${!tmp_var}" != "" ]; then
				needs_distro_version_found=1
				if [ "${ove_projects_needs[${i}]}" = "" ]; then
					ove_projects_needs[i]=$(eval echo ${!tmp_var})
				else
					ove_projects_needs[i]+=" $(eval echo ${!tmp_var})"
				fi
				unset ${tmp_var}
			elif [ $needs_distro_version_found -eq 0 ] && tmp_var="ove_YaMl_${name}_needs_${m//-/_}" && [ "${!tmp_var}" != "" ]; then
				if [ "${ove_projects_needs[${i}]}" = "" ]; then
					ove_projects_needs[i]=$(eval echo ${!tmp_var})
				else
					ove_projects_needs[i]+=" $(eval echo ${!tmp_var})"
				fi
				unset ${tmp_var}
			fi
		done

		# version
		tmp_var="ove_YaMl_${name}_version"
		ove_projects_version[i]=${!tmp_var}
		unset ${tmp_var}

		(( i+=1 ))
	done

	# unset any distro needs laying around
	unset $(compgen -A variable ove_YaMl_ | \
		while read -r v; do
			if [[ $v != *_needs_* ]]; then
				continue
			fi
			echo $v
		done)

	# re-define any leftovers
	for v in $(compgen -A variable ove_YaMl_); do
		eval ${v/_YaMl}='${!v}'
		unset ${v}
	done

	if ! ove_validate_projs; then
		return 1
	fi

	# OVE_BUILD_ORDER:project build order
	OVE_BUILD_ORDER="$(ove-build-order)"
	export OVE_BUILD_ORDER
}

function ove_list_projects_without_deps {
	local i

	i=0
	while ((i < ove_number_of_projects)); do
		if [ "${ove_projects_deps[${i}]}" = "" ]; then
			echo -n "${ove_projects_name[${i}]} "
		fi
		(( i+=1 ))
	done
}

function ove_list_projects_with_deps {
	local i

	i=0
	while ((i < ove_number_of_projects)); do
		if [ "${ove_projects_deps[${i}]}" != "" ]; then
			echo -n "${ove_projects_name[${i}]} "
		fi
		(( i+=1 ))
	done
}

# helper for ove_projects_cmd
function ove_projects_cmd_execute {
	local e
	local ret=0
	local s

	# command common?
	s="${OVE_OWEL_DIR}/projects/common/${proj_command}"
	if [ -s "${s}" ]; then
		if [ "${OVE_DRY_RUN}" -eq 1 ]; then
			ove_echo_stderr_noprefix "source ${s}"
		else
			OVE_ACTIVE_PROJECT_NAME="${proj_name}" \
				OVE_ACTIVE_PROJECT_COMMAND="${proj_command}" \
				OVE_ACTIVE_PROJECT_VERSION=${ove_projects_version[${i}]} \
				source "${s}"
			# preserve return code
			ret="$?"
		fi
	fi

	# project common?
	s="${OVE_OWEL_DIR}/projects/${proj_name}/common"
	if [ ${ret} -eq 0 ] && \
		[ -s "${s}" ]; then
		if [ "${OVE_DRY_RUN}" -eq 1 ]; then
			ove_echo_stderr_noprefix "source ${s}"
		else
			OVE_ACTIVE_PROJECT_NAME="${proj_name}" \
				OVE_ACTIVE_PROJECT_COMMAND="${proj_command}" \
				OVE_ACTIVE_PROJECT_VERSION=${ove_projects_version[${i}]} \
				source "${s}"
			# preserve return code
			ret="$?"
		fi
	fi

	# sanity check that the project command is executable
	s="${OVE_OWEL_DIR}/projects/${proj_name}/${proj_command}"
	if [ ${ret} -eq 0 ] && \
		[ -x "${s}" ]; then
		# "$1"/$2 is no longer needed
		shift 2

		e="${proj_name}_version=${ove_projects_version[${i}]}"
		e+=" OVE_ACTIVE_PROJECT_NAME=${proj_name}"
		e+=" OVE_ACTIVE_PROJECT_COMMAND=${proj_command}"
		e+=" OVE_ACTIVE_PROJECT_VERSION=${ove_projects_version[${i}]}"
		if [ ${OVE_TAINT_USER_ENV} -eq 0 ]; then
			e+=" LD_LIBRARY_PATH=${OVE_LD_LIBRARY_PATH}:${LD_LIBRARY_PATH}"
			e+=" MAKEFLAGS=\"\${OVE_MAKEFLAGS}\""
			e+=" PATH=${OVE_STAGE_DIR}${OVE_PREFIX}/sbin:${OVE_STAGE_DIR}${OVE_PREFIX}/bin:${PATH}"
			e+=" PKG_CONFIG_PATH=${OVE_PKG_CONFIG_PATH}"
		fi

		if [ "${OVE_DRY_RUN}" -eq 1 ]; then
			ove_echo_stderr_noprefix "eval ${e} ${s}"
		else
			# run the command
			eval "${e} \
				${s} \
				${OVE_REDIRECT_OUTPUT}"
			# preserve return code
			ret="$?"
		fi
	fi

	if [ "${ret}" -ne 0 ]; then
		ove_echo_error "${proj_name}: ${proj_command}"
	elif [ ${OVE_LOGLEVEL} -ne 0 ]; then
		ove_echo_cyan_error "${proj_name}: ${proj_command}: done"
	fi

	return $ret
}

# $1: project name
# $2: project command
function ove_project_has_step {
	if [ -e "${OVE_OWEL_DIR}/projects/${1}/${2}" ]; then
		return 0
	elif [ -e "${OVE_OWEL_DIR}/projects/common/${2}" ]; then
		return 0
	fi

	return 1
}

# $1: project name
# $2: project command
function ove_projects_cmd {
	local i
	local path
	local proj_command
	local proj_name
	local re
	local ret
	local with_flock=0

	proj_name=$1
	proj_command=$2
	ret=0

	if [ "${OVE_PROJECT_DISABLE}" != "" ]; then
		re=${OVE_PROJECT_DISABLE}
		if [[ "${proj_name}" =~ ${re} ]]; then
			return 0
		fi
	fi

	# sanity check
	if ! ove_project_has_step "${proj_name}" "${proj_command}"; then
		return 0
	fi

	i=${ove_projects_name2index[${proj_name}]}
	path="${ove_projects_path[${i}]}"

	# create dir if needed
	if [ ! -d "${path}" ]; then
		if ! ${ove_cmd2pathname["mkdir"]:?} -vp "${path}"; then
			ove_echo_warning_noprefix "${proj_name}: ${proj_command}: 'mkdir -vp ${path}' failed"
		fi
	fi

	if [ "${OVE_DRY_RUN}" -eq 1 ]; then
		ove_echo_stderr_noprefix "pushd ${path}"
	elif ! pushd "${path}" &>/dev/null; then
		ove_echo_error_noprefix "${proj_name}: ${proj_command}: pushd '${path}' failed"
		return 1
	fi

	if [ ${OVE_LOGLEVEL} -ne 0 ]; then
		ove_echo_cyan_error "${proj_name}: ${proj_command}"
	fi

	if [ "${OVE_FORCE_SERIALIZE_COMMANDS}" != "" ]; then
		re=\\b${proj_command}\\b
		if [[ "${OVE_FORCE_SERIALIZE_COMMANDS}" =~ ${re} ]]; then
			with_flock=1
		fi
	fi

	if [ ${with_flock} -eq 1 ]; then
		(
			${ove_cmd2pathname["flock"]:?} ${fd}
			ove_projects_cmd_execute "$@"
			exit $?
		) {fd}>${OVE_OWEL_TMP_DIR}/.${proj_command}.lock
		ret=$?
	else
		ove_projects_cmd_execute "$@"
		ret=$?
	fi

	if [ "${OVE_DRY_RUN}" -eq 1 ]; then
		ove_echo_stderr_noprefix "popd"
	elif ! popd &>/dev/null; then
		ove_echo_warning_noprefix "${proj_name}: ${proj_command}: popd failed"
	fi

	return "${ret}"
}

function ove_git_command_options_init {
	local k

	unset ove_revtab_git_cmd_opts
	declare -A -g ove_revtab_git_cmd_opts

	# default git command options
	ove_read_git_command_options

	# remember the default values
	unset ove_revtab_git_cmd_opts_default
	declare -A -g ove_revtab_git_cmd_opts_default
	for k in "${!ove_revtab_git_cmd_opts[@]}"; do
		ove_revtab_git_cmd_opts_default[$k]=${ove_revtab_git_cmd_opts[$k]}
	done

	# overrides?
	if [ "${OVE_GIT_COMMAND_OPTIONS_OVERRIDE}" != "" ]; then
		OVE_GIT_COMMAND_OPTIONS_DEFAULT="${OVE_GIT_COMMAND_OPTIONS_OVERRIDE}" ove_read_git_command_options
	fi

	return 0
}

function ove_read_git_command_options {
	local cmd
	local cmd_opt
	local i
	local o
	local re
	local re_cmd
	local repo
	declare -A pattern
	declare -a opt

	if [ "${OVE_GIT_COMMAND_OPTIONS_DEFAULT}" != "" ]; then
		while IFS=';' read -a opt -r; do
			for o in "${opt[@]}"; do
				if [[ ! $o == *:* ]] || [[ ! $o == *@* ]]; then
					ove_echo_error_noprefix "format error: '$o'"
					continue
				fi
				re=${o%%:*}
				re=${re%@*}

				if [ "$re" = ".*" ]; then
					cmd=${o%%:*}
					cmd=${cmd#*@}
					cmd_opt=${o#*:}
					ove_revtab_git_cmd_opts["*:${cmd}"]="${cmd_opt}"
					continue
				fi
				re=\\b$re\\b

				if [[ ! "${ove_revtab_git_name[*]} $OVE_OWEL_NAME" =~ $re ]]; then
					continue
				fi

				# at least one repo match this pattern, remember the pattern
				cmd=${o%%:*}
				cmd=${cmd#*@}
				cmd_opt=${o#*:}
				pattern["$re:$cmd"]="$cmd_opt"
			done
		done <<<"${OVE_GIT_COMMAND_OPTIONS_DEFAULT}"

		for re_cmd in "${!pattern[@]}"; do
			for repo in "${ove_revtab_git_name[@]}" $OVE_OWEL_NAME; do
				re=${re_cmd%%:*}
				if [[ ! $repo =~ $re ]]; then
					continue
				fi
				cmd=${re_cmd#*:}
				cmd_opt=${pattern[$re_cmd]}
				if [ "${cmd_opt}" = "" ]; then
					continue
				fi
				ove_revtab_git_cmd_opts["${repo//\./}:${cmd}"]="${cmd_opt}"
			done
		done
	fi
}

# list-git-command-options: :list git command options (d=default, o=override):CORE
function ove-list-git-command-options {
	ove_entry || return

	local k
	local s

	for k in ${!ove_revtab_git_cmd_opts[*]}; do
		s="d"
		if [ "${ove_revtab_git_cmd_opts[$k]}" != "${ove_revtab_git_cmd_opts_default[$k]}" ]; then
			s="o"
		fi
		echo "${s}:${k}:${ove_revtab_git_cmd_opts[$k]}"
	done | ${ove_cmd2pathname["column"]:?} -t -s: | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

function ove_revtab_init {
	local array
	local line
	local lineno=0

	unset ove_revtab_fetch_url
	unset ove_revtab_push_url
	unset ove_revtab_rev
	unset ove_revtab_git_name
	unset ove_revtab_name2index
	ove_revtab_num_repositories=0

	if [ ! -e "${OVE_OWEL_DIR}/revtab" ]; then
		OVE_REPO_LIST="${OVE_OWEL_DIR}"
		OVE_REPO_LIST_WIDTH="${#OVE_OWEL_NAME}"
		((OVE_REPO_LIST_WIDTH+=2))
		return
	fi

	if ! ove_revtab_validate; then
		return 1
	fi

	declare -a -g ove_revtab_fetch_url
	declare -a -g ove_revtab_push_url
	declare -a -g ove_revtab_rev
	declare -a -g ove_revtab_git_name
	declare -A -g ove_revtab_name2index

	OVE_REPO_LIST_WIDTH="${#OVE_OWEL_NAME}"
	while read -r line; do
		(( lineno+=1 ))
		# skip comments and blank lines
		if [ "${line:0:1}" = "#" ]; then
			continue
		elif [ "${line}" = "" ]; then
			continue
		fi

		read -a array -r <<<"${line}"

		if [ "${array[1]}" = "" ] || [ "${array[2]}" = "" ] || [ "${array[3]}" = "" ] || [ "${#array[*]}" -gt 4 ]; then
			ove_echo_warning_noprefix "${OVE_OWEL_DIR}/revtab:${lineno} format error"
			continue
		fi

		if [ "${array[0]}" = "${OVE_OWEL_NAME}" ]; then
			ove_echo_error_noprefix "${OVE_OWEL_DIR}/revtab:${lineno}: name violation"
			return 1
		fi

		ove_revtab_git_name[ove_revtab_num_repositories]=${array[0]}
		ove_revtab_fetch_url[ove_revtab_num_repositories]=${array[1]}
		ove_revtab_push_url[ove_revtab_num_repositories]=${array[2]}
		ove_revtab_rev[ove_revtab_num_repositories]=${array[3]}
		ove_revtab_name2index[${array[0]}]=${ove_revtab_num_repositories}
		if ! [ -e "${OVE_OWEL_TMP_DIR}/.${ove_revtab_num_repositories}.lock" ]; then
			true > "${OVE_OWEL_TMP_DIR}/.${ove_revtab_num_repositories}.lock"
		fi

		if [ $OVE_REPO_LIST_WIDTH -lt ${#ove_revtab_git_name[${ove_revtab_num_repositories}]} ]; then
			OVE_REPO_LIST_WIDTH=${#ove_revtab_git_name[${ove_revtab_num_repositories}]}
		fi
		(( ove_revtab_num_repositories+=1 ))
	done < "${OVE_OWEL_DIR}/revtab"
	((OVE_REPO_LIST_WIDTH+=2))

	if ! [ -e "${OVE_OWEL_TMP_DIR}/.owel.lock" ]; then
		true > "${OVE_OWEL_TMP_DIR}/.owel.lock"
	fi

	# OVE_REPO_LIST:space separated list of all git repositories for one OVE workspace
	OVE_REPO_LIST=$(ove_revtab_list_fullpath)
	export OVE_REPO_LIST

	# OVE_REPO_LIST_WIDTH:longest repo name
	export OVE_REPO_LIST_WIDTH
}

# $1: repo name (either 'name' or '${OVE_BASE_DIR}/'name')
function ove_repo2fullpath {
	local i
	local name
	local repo_fullpath

	name=${1/${OVE_BASE_DIR}\/}
	if [ "${name}" = "${OVE_OWEL_NAME}" ]; then
		repo_fullpath="${OVE_BASE_DIR}/${OVE_OWEL_NAME}"
	elif [[ -v ove_revtab_name2index[${name}] ]]; then
		i=${ove_revtab_name2index[${name}]}
		repo_fullpath="${OVE_BASE_DIR}/${ove_revtab_git_name[${i}]}"
	fi

	echo ${repo_fullpath}
}

# $1: repo name (either 'name' or '${OVE_BASE_DIR}/'name')
function ove_repo2shortpath {
	local i
	local name
	local repo_shortpath

	if [ $# -ne 1 ]; then
		return 1
	fi

	name=${1/${OVE_BASE_DIR}\/}
	if [ "${name}" = "${OVE_OWEL_NAME}" ]; then
		repo_shortpath="${OVE_OWEL_NAME}"
	elif [[ -v ove_revtab_name2index[${name}] ]]; then
		i=${ove_revtab_name2index[${name}]}
		repo_shortpath="${ove_revtab_git_name[${i}]}"
	fi

	echo ${repo_shortpath}
}

# $1: repo name (either 'name' or '${OVE_BASE_DIR}/'name')
function ove_repo2index {
	local i
	local name

	if [ $# -ne 1 ]; then
		return 1
	fi

	name=${1/${OVE_BASE_DIR}\/}
	if [ "${name}" = "${OVE_OWEL_NAME}" ]; then
		echo "${OVE_OWEL_NAME}"
	elif [[ -v ove_revtab_name2index[${name}] ]]; then
		i=${ove_revtab_name2index[${name}]}
		echo ${i}
	fi
}

# $1: dir
function ove_dir_is_repo {
	if [ -d "${1}" ] && [ -e "${1}"/.git ]; then
		return 0
	fi

	return 1
}

# $1: repo
function ove_status_one_repo {
	local git_opt
	local i
	local len
	local m
	local override=0
	local repo_fullpath
	local repo_shortpath
	local revision
	local s

	if [ $# -ne 1 ]; then
		return 1
	fi

	repo_fullpath=$(ove_repo2fullpath $1)
	if [ "${repo_fullpath}" = "" ]; then
		return
	elif ! ove_dir_is_repo "${repo_fullpath}"; then
		return
	fi

	repo_shortpath="$(ove_repo2shortpath $1)"

	if [ "${repo_shortpath}" = "${OVE_OWEL_NAME}" ]; then
		revision="$(ove_repo_cmd "${OVE_OWEL_DIR}" "describe" --tags --always 2> /dev/null)"
		if [ -z "${revision}" ]; then
			revision=" "
		fi
	else
		i=${ove_revtab_name2index[${repo_shortpath}]}
		revision="${ove_revtab_rev[${i}]}"
	fi

	# only allow overrides from 'ove-status'
	if [ ${FUNCNAME[-1]} = "ove-status" ]; then
		override=1
	elif [ ! -v ove_revtab_git_cmd_opts_default ]; then
		git_opt="-bs -uno"
	else
		git_opt=${ove_revtab_git_cmd_opts_default['*:status']}
	fi

	if ! s=$(ALLOW_OVERRIDE=${override} ove_repo_cmd "${repo_fullpath}" "${OVE_GIT_OPTIONS} -c color.status=always status" ${git_opt} 2> /dev/null); then
		s="$(ove_echo_red_noprefix '??')"
	else
		len=${#s}
		if [ ${OVE_STATUS_TRUNC:?} -eq 1 ] && [ "$OVE_COLUMNS" != "" ] && [ ${len} -gt $((OVE_COLUMNS*OVE_LINES)) ]; then
			m="$((OVE_COLUMNS*$((OVE_LINES/2 - 1))))"
			s="${s:0:${m}} $(ove_echo_yellow_noprefix ...truncated $((len-m*2)) chars...) ${s: -${m}}"
		fi
	fi

	if [[ "${OVE_STATUS_TRUNC_REVISION}" =~ ^[0-9]+$ ]] && [ ${OVE_STATUS_TRUNC_REVISION} -ne 0 ]; then
		revision=${revision:0:${OVE_STATUS_TRUNC_REVISION}}
	fi
	printf "$(printf "%-$((OVE_REPO_LIST_WIDTH-2))s" ${repo_shortpath}):${revision}:$(printf "%s " $s)\n"
}

function ove_validate_repo_list {
	local out
	local repos

	while true; do
		if [ $# -eq 0 ]; then
			break
		elif [[ "$1" == *[[:space:]]* ]]; then
			:
		elif [ "$1" = "${OVE_OWEL_NAME}" ] || [[ -v ove_revtab_name2index[${1}] ]]; then
			repos+="$(ove_repo2shortpath $1) "
		fi
		shift
	done

	if [ "${repos}" = "" ]; then
		return
	fi

	out=$(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u < <(printf "%s\n" ${repos}))
	if [ "${out}" != "" ]; then
		echo ${out}
	fi
}

function ove_revtab_status {
	local f
	local files
	local i
	local repo
	local repos
	local o

	if [ $# -ge 1 ]; then
		repos=$(ove_validate_repo_list "$@")
	else
		repos=${OVE_REPO_LIST}
	fi

	if [ "${repos}" = "" ]; then
		return
	fi

	if [ -w "${OVE_OWEL_STATE_DIR}" ]; then
		f="${OVE_OWEL_STATE_DIR}"
	else
		f="${OVE_TMP}"
	fi
	o=${f}

	f+="/$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S%N')-revtab-status"

	i=0
	for repo in ${repos}; do
		ove_status_one_repo ${repo} > ${f}.${i} &
		i=$((i + 1))
	done
	wait

	files=
	i=0
	for repo in ${repos}; do
		files+="${f}.$i "
		i=$((i + 1))
	done

	${ove_cmd2pathname["cat"]:?} ${files} > ${f}
	${ove_cmd2pathname["rm"]:?} ${files}

	LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -o ${f} ${f}
	if [ "${OVE_COLUMN_WRAP_BUG}" -eq 1 ]; then
		${ove_cmd2pathname["column"]:?} -t -s: <<<"$(${ove_cmd2pathname["fold"]:?} -w 2048 -s ${f})"
	else
		${ove_cmd2pathname["column"]:?} -t -s: <${f}
	fi

	${ove_cmd2pathname["mv"]:?} "${f}" "${o}/revtab-status"
}

# $1: ahead|behind
function ove_revtab_status_parse_one {
	local branch_status
	local git_args
	local git_fmt
	local repo_fullpath
	local i
	local nbr_commits
	local tense

	tense=$1
	shift

	git_fmt='%<(15,trunc)%h?%<(15,trunc)%ar?%<(40,mtrunc)%ae?%s'
	repo_fullpath=$(ove_repo2fullpath $1)

	if [ "${repo_fullpath}" = "" ]; then
		return
	elif ! ove_dir_is_repo "${repo_fullpath}"; then
		return
	fi

	branch_status=$(${ove_cmd2pathname["git"]:?} \
		-C "${repo_fullpath}" \
		branch \
		-v \
		--format="%(upstream:track,nobracket)" \
		--list $(${ove_cmd2pathname["git"]:?} \
			-C "${repo_fullpath}" \
			rev-parse \
			--abbrev-ref HEAD))
	nbr_commits=0
	if [[ "${branch_status}" == *"${tense}"* ]]; then
		if [ "${tense}" = "ahead" ]; then
			branch_status=${branch_status%%,*}
			nbr_commits=${branch_status##"${tense}" }
		elif [ "${tense}" = "behind" ]; then
			if ! ${ove_cmd2pathname["git"]:?} -C "${repo_fullpath}" cat-file -e FETCH_HEAD 2> /dev/null; then
				return 1
			fi
			nbr_commits=${branch_status##*"${tense}" }
			git_args="FETCH_HEAD"
		else
			return 1
		fi

		ove_echo_yellow_noprefix "$(ove_repo2shortpath $1): ${nbr_commits} new commit(s):"
		${ove_cmd2pathname["git"]:?} --no-pager -C "${repo_fullpath}" log ${git_args} -n ${nbr_commits} --format="${git_fmt}" | \
			${ove_cmd2pathname["column"]:?} -t -s?
		echo
	fi
}

# $1   : ahead|behind
# $2...: optional list of repositories
function ove_revtab_status_parse {
	local repo
	local repos
	local tense

	if [ $# -eq 0 ]; then
		return 1
	fi

	tense="$1"
	shift

	# turn off monitor mode to get rid of "Done" messages
	set +m

	if [ $# -ge 1 ]; then
		repos=$(ove_validate_repo_list "$@")
	elif ove_any_repo ${tense}; then
		repos=$(ove_list_repositories ${tense})
	else
		return 0
	fi

	for repo in ${repos}; do
		ove_revtab_status_parse_one ${tense} ${repo}
	done | ${ove_cmd2pathname["head"]:?} -n -1

	# turn on monitor mode
	set -m
}

function ove_revtab_sanity {
	if [ "${ove_revtab_num_repositories}" -eq 0 ]; then
		return 1
	fi
}

function ove_repos_fetched {
	local f=0
	local repo

	for repo in ${OVE_REPO_LIST}; do
		if [ -e ${repo}/.git ]; then
			(( f+=1 ))
		fi
	done

	echo ${f}
}

function ove_verify_checksums {
	local cfgs
	local md5

	ove_externals_init

	# OVE_BASE_DIR got lost? keep this as early as possible
	if [ -z "${OVE_BASE_DIR+x}" ]; then
		return 1
	fi

	if [ ${OVE_REVTAB_CHECK} -eq 1 ]; then
		md5=$(ove_repos_fingerprint)
		# got updated?
		if [ -n "${OVE_REPOS_MD5+x}" ] && [ "${md5}" != "${OVE_REPOS_MD5}" ]; then
			return 1
		fi
	fi

	if [ -e "${OVE_OWEL_DIR}/revtab" ]; then
		md5=$(${ove_cmd2pathname["md5sum"]:?} ${OVE_OWEL_DIR}/revtab)
		md5=${md5%% *}
		# got updated?
		if [ -n "${OVE_REVTAB_MD5+x}" ] && [ "${md5}" != "${OVE_REVTAB_MD5}" ]; then
			return 1
		# just created?
		elif [ -z "${OVE_REVTAB_MD5+x}" ]; then
			return 1
		fi
	elif [ -n "${OVE_REVTAB_MD5+x}" ]; then
		# got removed?
		unset OVE_REVTAB_MD5
		return 1
	fi

	if [ -e "${OVE_OWEL_DIR}/projs" ]; then
		md5=$(${ove_cmd2pathname["md5sum"]:?} ${OVE_OWEL_DIR}/projs)
		md5=${md5%% *}
		# got updated?
		if [ -n "${OVE_PROJS_MD5+x}" ] && [ "${md5}" != "${OVE_PROJS_MD5}" ]; then
			return 1
		# just created?
		elif [ -z "${OVE_PROJS_MD5+x}" ]; then
			return 1
		fi
	elif [ -n "${OVE_PROJS_MD5+x}" ]; then
		# got removed?
		unset OVE_PROJS_MD5
		return 1
	fi

	read -r -a cfgs < <(ove_list_oveconfig_files_all)
	if [ "${#cfgs[@]}" -ne 0 ]; then
		md5=$(ove_file_fingerprint "${cfgs[@]}")
		# got updated?
		if [ -n "${OVE_CONFIG_MD5+x}" ] && [ "${md5}" != "${OVE_CONFIG_MD5}" ]; then
			return 1
		# just created?
		elif [ -z "${OVE_CONFIG_MD5+x}" ]; then
			return 1
		fi
	elif [ -n "${OVE_CONFIG_MD5+x}" ]; then
		# got removed?
		unset OVE_CONFIG_MD5
		return 1
	fi

	# ignore large files laying around in the scripts directories
	md5=$(HASH_SIZE_THRESHOLD=$OVE_HASH_SIZE_THRESHOLD_IN_BYTES ove_file_fingerprint $(ove_list_scripts_directories))
	# got updated?
	if [ -n "${OVE_SCRIPTS_CONTENT_MD5+x}" ] && [ "${md5}" != "${OVE_SCRIPTS_CONTENT_MD5}" ]; then
		return 1
	fi

	md5=$(ove-list-scripts | ${ove_cmd2pathname["md5sum"]:?})
	md5=${md5%% *}
	# got updated?
	if [ -n "${OVE_SCRIPTS_NAMES_MD5+x}" ] && [ "${md5}" != "${OVE_SCRIPTS_NAMES_MD5}" ]; then
		return 1
	fi

	md5=$(ove-list-hooks | ${ove_cmd2pathname["md5sum"]:?})
	md5=${md5%% *}
	# got updated?
	if [ -n "${OVE_HOOKS_NAMES_MD5+x}" ] && [ "${md5}" != "${OVE_HOOKS_NAMES_MD5}" ]; then
		return 1
	fi

	if [ "${OVE_REPOS_FETCHED}" != "" ] && [ $(ove_repos_fetched) -ne ${OVE_REPOS_FETCHED} ]; then
		return 1
	fi

	return 0
}

function ove_update_checksum_config {
	local cfgs

	read -r -a cfgs < <(ove_list_oveconfig_files_all)
	if [ ${#cfgs[@]} -ne 0 ]; then
		OVE_CONFIG_MD5=$(ove_file_fingerprint "${cfgs[@]}")
		export OVE_CONFIG_MD5
	fi
}

function ove_repos_fingerprint {
	local md5

	md5=$(ove_revtab_forall_parallel ${ove_cmd2pathname["stat"]:?} --format '%Y' .git/HEAD 2> /dev/null | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["md5sum"]:?})
	md5=${md5%% *}
	echo "${md5}"
}

function ove_update_checksum {
	local md5

	if [ -e "${OVE_OWEL_DIR}/revtab" ]; then
		md5=$(${ove_cmd2pathname["md5sum"]:?} ${OVE_OWEL_DIR}/revtab)
		md5=${md5%% *}
		OVE_REVTAB_MD5=${md5}
		export OVE_REVTAB_MD5
	fi

	if [ -e "${OVE_OWEL_DIR}/projs" ]; then
		md5=$(${ove_cmd2pathname["md5sum"]:?} ${OVE_OWEL_DIR}/projs)
		md5=${md5%% *}
		OVE_PROJS_MD5=${md5}
		export OVE_PROJS_MD5
	fi

	ove_update_checksum_config

	if [ ${OVE_REVTAB_CHECK} -eq 1 ]; then
		OVE_REPOS_MD5=$(ove_repos_fingerprint)
		export OVE_REPOS_MD5
	fi

	# ignore large files laying around in the scripts directories
	OVE_SCRIPTS_CONTENT_MD5=$(HASH_SIZE_THRESHOLD=$OVE_HASH_SIZE_THRESHOLD_IN_BYTES ove_file_fingerprint "${!ove_scripts_paths[@]}")
	export OVE_SCRIPTS_CONTENT_MD5

	OVE_SCRIPTS_NAMES_MD5=$(ove-list-scripts | ${ove_cmd2pathname["md5sum"]:?})
	OVE_SCRIPTS_NAMES_MD5=${OVE_SCRIPTS_NAMES_MD5%% *}
	export OVE_SCRIPTS_NAMES_MD5

	OVE_HOOKS_NAMES_MD5=$(ove-list-hooks | ${ove_cmd2pathname["md5sum"]:?})
	OVE_HOOKS_NAMES_MD5=${OVE_HOOKS_NAMES_MD5%% *}
	export OVE_HOOKS_NAMES_MD5

	OVE_REPOS_FETCHED=$(ove_repos_fetched)
	export OVE_REPOS_FETCHED
}

# $1: name
# $2: fetch url
# $3: push url
function ove_revtab_check_fetch_push {
	local name
	local remote
	local remote_url
	local revtab_url

	name=$1
	if [ ! -e "${OVE_BASE_DIR}/${name}/.git" ]; then
		return
	fi

	# skip multiple remotes (for now)
	if [ $(ove_get_nbr_of_remotes "${OVE_BASE_DIR}/${name}") -gt 1 ]; then
		return
	elif ! remote=$(${ove_cmd2pathname["git"]:?} -C "${OVE_BASE_DIR}/${name}" remote 2> /dev/null); then
		return
	fi

	# fetch URL
	if ! remote_url=$(${ove_cmd2pathname["git"]:?} -C "${OVE_BASE_DIR}/${name}" "remote" get-url "${remote}" 2> /dev/null); then
		return
	fi
	revtab_url="$2"
	if [ "${remote_url}" != "${revtab_url}" ]; then
		ove_repo_cmd "${OVE_BASE_DIR}/${name}" "remote" set-url "${remote}" "${revtab_url}"
	fi

	# push URL
	if ! remote_url=$(${ove_cmd2pathname["git"]:?} -C "${OVE_BASE_DIR}/${name}" "remote" get-url --push "${remote}" 2> /dev/null); then
		return
	fi
	revtab_url="$3"
	if [ "${remote_url}" != "${revtab_url}" ]; then
		ove_repo_cmd "${OVE_BASE_DIR}/${name}" "remote" set-url --push "${remote}" "${revtab_url}"
	fi
}

# $1: name
# $2: fetch url
# $3: push url
# $4: rev
function ove_revtab_check_one {
	local branch_name
	local co=0
	local detached=0
	local name
	local rev_is_branch=0
	local revision
	local sha_a
	local sha_b

	name=$1
	if [ ! -e "${OVE_BASE_DIR}/${name}/.git" ]; then
		return
	fi

	revision=$4
	sha_a=$(${ove_cmd2pathname["git"]:?} -C ${OVE_BASE_DIR}/${name} rev-list -n 1 --abbrev-commit HEAD --)
	if ! sha_b=$(${ove_cmd2pathname["git"]:?} -C ${OVE_BASE_DIR}/${name} rev-list -n 1 --abbrev-commit ${revision} -- 2> /dev/null); then
		sha_b=""
	fi

	if [ "${sha_a}" != "${sha_b}" ]; then
		# diff => checkout
		co=1
	else
		if ! ${ove_cmd2pathname["git"]:?} -C "${OVE_BASE_DIR}/${name}" symbolic-ref -q HEAD > /dev/null; then
			detached=1
		fi

		if ${ove_cmd2pathname["git"]:?} -C ${OVE_BASE_DIR}/${name} show-ref -q --heads $revision; then
			rev_is_branch=1
		fi

		# detached and rev is a branch => checkout
		if [ ${detached} -eq 1 ] && [ ${rev_is_branch} -eq 1 ]; then
			co=1
		# not detached and rev is not a branch => checkout
		elif [ ${detached} -eq 0 ] && [ ${rev_is_branch} -eq 0 ]; then
			co=1
		# switched branch?
		elif [ ${detached} -eq 0 ] && [ ${rev_is_branch} -eq 1 ]; then
			branch_name=$(${ove_cmd2pathname["git"]:?} -C ${OVE_BASE_DIR}/${name} rev-parse --abbrev-ref HEAD)
			if [ "${branch_name}" != "${revision}" ]; then
				co=1
			fi
		fi
	fi

	if [ ${co} -eq 1 ]; then
		if ove_repo_is_dirty ${OVE_BASE_DIR}/${name}; then
			ove_echo_error_noprefix "${name}: cannot checkout '${revision}' as repo is dirty"
		else
			ove_revtab_checkout ${name}
		fi
	fi

	ove_revtab_check_fetch_push "$1" "$2" "$3"
}

# revtab-sync:[git...]:sync all/specified git repositories with 'revtab' (override OVE_REVTAB_CHECK):CORE
function ove-revtab-sync {
	ove_entry || return
	ove_revtab_sanity || return

	local i
	local r
	local repos

	if [ $# -eq 0 ]; then
		repos="${OVE_REPO_LIST}"
	else
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			echo "error: invalid repo name: '${*}'" 1>&2
			return 1
		fi
	fi

	for r in ${repos}; do
		i=$(ove_repo2index ${r})
		if [ "$i" = "${OVE_OWEL_NAME}" ]; then
			continue
		fi
		ove_revtab_check_one \
			${ove_revtab_git_name[${i}]} \
			${ove_revtab_fetch_url[${i}]} \
			${ove_revtab_push_url[${i}]} \
			${ove_revtab_rev[${i}]} &
	done | ${ove_cmd2pathname["grep"]:?} -v '^\[' || true
	wait
}

function ove_revtab_check {
	ove_revtab_sanity || return

	local i
	local n=${FUNCNAME^^}
	local name

	if [ -n "${!n}" ] && [ "${!n}" -eq 0 ]; then
		return
	fi

	# turn off monitor mode to get rid of "Done" messages
	set +m

	i=0
	while ((i < ove_revtab_num_repositories)); do
		name="${ove_revtab_git_name[${i}]}"
		# ignore patched repos
		if [ -d "${OVE_OWEL_DIR}/patches/${name}" ]; then
			(( i+=1 ))
			continue
		fi

		ove_revtab_check_one \
			${name} \
			${ove_revtab_fetch_url[${i}]} \
			${ove_revtab_push_url[${i}]} \
			${ove_revtab_rev[${i}]} &
		(( i+=1 ))
	done | ${ove_cmd2pathname["grep"]:?} -v '^\[' || true
	wait

	# turn on monitor mode
	set -m
}

function ove_revtab_list_fullpath {
	local repo
	local s

	for repo in "${ove_revtab_git_name[@]}"; do
		s+="${OVE_BASE_DIR}/${repo} "
	done
	s+="${OVE_OWEL_DIR}"

	echo ${s}
}

function ove_revtab_list_basename {
	local repo
	local s

	for repo in "${ove_revtab_git_name[@]}" ${OVE_OWEL_NAME}; do
		s+="${repo} "
	done

	echo ${s}
}

function ove_revtab_forall {
	local repo
	local repo_basename

	for repo in ${OVE_REPO_LIST}; do
		if ! ove_dir_is_repo "${repo}"; then
			continue
		fi
		repo_basename=${repo/${OVE_BASE_DIR}\/}
		eval "pushd ${repo} &>/dev/null && $1; popd&>/dev/null"
	done
}

function ove_cap_jobs {
	local job_list

	if [ $# -ne 1 ] || [ $1 -eq 0 ]; then
		return
	fi

	mapfile -t job_list < <(jobs -p -r)
	if [ "${#job_list[@]}" -ge "${1}" ]; then
		wait -n
	fi
}

# $1: max_parallel
# $2: command
# $3: args
function ove_git_cmd_forall_parallel {
	(
	local cmd
	local max_parallel
	local repo
	local repo_basename

	max_parallel=$1
	shift
	cmd=$1
	shift

	for repo in ${OVE_REPO_LIST}; do
		if [ ! -d "${repo}" ]; then
			continue
		fi
		repo_basename=${repo/${OVE_BASE_DIR}\/}
		ove_repo_cmd "$repo" "$cmd" "$@" | ${ove_cmd2pathname["sed"]:?} -e "s,^,${repo}/,g" &
		ove_cap_jobs ${max_parallel}
	done
	wait
	)
}

# $1: command
# $2: max number of jobs
function ove_revtab_forall_parallel {
	(
	local max_parallel=0
	local repo
	local repo_basename

	if [ $# -eq 2 ]; then
		max_parallel=$2
	fi

	for repo in ${OVE_REPO_LIST}; do
		if ! ove_dir_is_repo "${repo}"; then
			continue
		fi
		repo_basename=${repo/${OVE_BASE_DIR}\/}
		if ! pushd "${repo}" &>/dev/null; then
			continue
		fi
		eval "$1" &
		ove_cap_jobs ${max_parallel}
	done
	wait
	)
}

function ove_revtab_forsome {
	local i
	local repo
	local repo_basename

	for i in "${@:2}"; do
		for repo in ${OVE_REPO_LIST}; do
			if ! ove_dir_is_repo "${repo}"; then
				continue
			elif [ "${repo}" = "${OVE_BASE_DIR}/${i}" ]; then
				repo_basename=${repo/${OVE_BASE_DIR}\/}
				eval "pushd ${repo} &>/dev/null && $1; popd&>/dev/null"
			fi
		done
	done
}

# $1  : cmd
# $2  : max jobs
# $3..: repos
function ove_revtab_forsome_parallel {
	(
	local repo
	local i

	for i in "${@:3}"; do
		for repo in ${OVE_REPO_LIST}; do
			if ! ove_dir_is_repo "${repo}"; then
				continue
			elif [ "${repo}" = "${OVE_BASE_DIR}/${i}" ]; then
				eval "pushd ${repo} &>/dev/null; $1; popd&>/dev/null" &
				ove_cap_jobs ${2}
			fi
		done
	done
	wait
	)
}

function ove_revtab_clone_and_checkout_one {
	local fetch_url
	local i=$1
	local name
	local push_url
	local sleep_s
	local try

	fetch_url="${ove_revtab_fetch_url[${i}]}"
	push_url="${ove_revtab_push_url[${i}]}"
	name="${ove_revtab_git_name[${i}]}"
	try=0

	if [ "$fetch_url" = "noremote" ]; then
		return
	fi

	while true; do
		try=$((try + 1))
		while true; do
			if ! ALLOW_OVERRIDE=1 ove_repo_cmd "${OVE_BASE_DIR}/${name}" "-c advice.detachedHead=false clone" "${fetch_url}" "${OVE_BASE_DIR}/${name}"; then
				return 1
			fi
			break
		done |& ${ove_cmd2pathname["sed"]:?} "s|^|$(printf "%-${OVE_REPO_LIST_WIDTH}s" ${name})|g"

		if [ ${PIPESTATUS[0]} -ne 0 ]; then
			if [ ${try} -eq ${OVE_CLONE_RETRY:?} ]; then
				ove_echo_error_noprefix "'git clone ${fetch_url} ${OVE_BASE_DIR}/${name}' failed"
				return 1
			else
				if [[ "${OVE_CLONE_RETRY_PERIOD:?}" == *","* ]] || [[ "${OVE_CLONE_RETRY_PERIOD:?}" == *"."* ]]; then
					ove_echo_error_noprefix "OVE_CLONE_RETRY_PERIOD: no floats"
					return 1
				fi

				if [ "${OVE_CLONE_RETRY_PERIOD:?}" -eq 0 ]; then
					continue
				elif [ "${OVE_CLONE_RETRY_PERIOD:?}" -lt 0 ]; then
					sleep_s=$((RANDOM%${OVE_CLONE_RETRY_PERIOD/-} + 1))
				else
					sleep_s=${OVE_CLONE_RETRY_PERIOD:?}
				fi
				ove_echo_cyan_noprefix "'git clone ${fetch_url} ${OVE_BASE_DIR}/${name}' try ${try}/${OVE_CLONE_RETRY} failed - retry in ${sleep_s} seconds"
				${ove_cmd2pathname["sleep"]:?} ${sleep_s}
				continue
			fi
		fi

		break
	done

	ove_revtab_checkout "${name}"
	ove_revtab_check_fetch_push "${name}" "${fetch_url}" "${push_url}"
	ove_patch_repos ${name} || true

	if [ -e "${OVE_BASE_DIR}/${name}/.gitmodules" ]; then
		if [ ${OVE_FETCH_SUBMODULES} -eq 1 ]; then
			if ! ove-import-submodules ${name}; then
				return 1
			fi
		else
			printf "%-${OVE_REPO_LIST_WIDTH}s%s\n" ${name} "$(ove_echo_note_noprefix "run 'ove import-submodules ${name}' to import $(${ove_cmd2pathname["grep"]:?} -c '\[submodule' "${OVE_BASE_DIR}/${name}/.gitmodules") git submodule(s)")"
		fi
	fi

	return 0
}

# $*: optional list of repositories
function ove_revtab_clone_and_checkout {
	(
	ove_revtab_sanity || return

	local i
	local repo
	local repos

	if [ $# -gt 0 ]; then
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			return 1
		fi
		for repo in ${repos}; do
			if [ ! -d "${OVE_BASE_DIR}/${repo}" ] || \
				[ "$(${ove_cmd2pathname["find"]:?} "${OVE_BASE_DIR}/${repo}/" -mindepth 1 -maxdepth 1)" = "" ]; then
				i=${ove_revtab_name2index[${repo}]}
				ove_revtab_clone_and_checkout_one ${i} &
				ove_cap_jobs ${OVE_CLONE_MAX_PARALLEL}
			fi
		done
	else
		i=0
		while ((i < ove_revtab_num_repositories)); do
			if [ ! -d "${OVE_BASE_DIR}/${ove_revtab_git_name[${i}]}" ] || \
				[ "$(${ove_cmd2pathname["find"]:?} "${OVE_BASE_DIR}/${ove_revtab_git_name[${i}]}/" -mindepth 1 -maxdepth 1)" = "" ]; then

				ove_revtab_clone_and_checkout_one ${i} &
				ove_cap_jobs ${OVE_CLONE_MAX_PARALLEL}
			fi
			(( i+=1 ))
		done
	fi

	wait
	)
}

function ove_revtab_checkout_one {
	local name
	local revision

	name=${ove_revtab_git_name[${1}]}
	revision=${ove_revtab_rev[${1}]}
	while true; do
		if ! ove_repo_cmd "${OVE_BASE_DIR}/${name}" "-c advice.detachedHead=false checkout" "${revision}" "--"; then
			ove_echo_error_noprefix "checkout '${revision}' failed"
			return 1
		fi
		break
	done |& ${ove_cmd2pathname["sed"]:?} -e "s|^|$(printf "%-${OVE_REPO_LIST_WIDTH}s" ${name})|g"
}

# $*: optional list of repositories
function ove_revtab_checkout {
	(
	local i
	local repo
	local repos

	if [ $# -gt 0 ]; then
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			return 1
		fi
		for repo in ${repos}; do
			i=${ove_revtab_name2index[${repo}]}
			ove_revtab_checkout_one ${i} &
		done
	else
		i=0
		while ((i < ove_revtab_num_repositories)); do
			ove_revtab_checkout_one ${i} &
			(( i+=1 ))
		done
	fi

	wait
	)
}

# helper that will return 1 if git config email or name is not set
function ove_git_config_check {
	if [ "$(${ove_cmd2pathname["git"]:?} config --global user.email)" = "" ] || \
		[ "$(${ove_cmd2pathname["git"]:?} config --global user.name)" = "" ]; then
		return 1
	else
		return 0
	fi
}

function ove_revtab_pull_one {
	local base
	local loc
	local remote
	local repo
	local repo_fullpath
	local upstream

	repo="$1"
	upstream="@{u}"

	repo_fullpath=$(ove_repo2fullpath $1)
	if [ "${repo_fullpath}" = "" ] || [ ! -d "${repo_fullpath}" ]; then
		return
	fi

	# check if detached
	if ! ove_repo_cmd "${repo_fullpath}" "rev-parse" -q "${upstream}" &> /dev/null; then
		return
	fi

	loc=$(ove_repo_cmd "${repo_fullpath}" rev-parse @)
	remote=$(ove_repo_cmd "${repo_fullpath}" rev-parse "${upstream}")
	base=$(ove_repo_cmd "${repo_fullpath}" merge-base @ "${upstream}")

	if [ "${loc}" = "${remote}" ]; then
		# up-to-date
		:
	elif [ "${remote}" = "${base}" ]; then
		# need to push
		:
	else
		if [ "$(ove_revtab_status_parse_one ahead ${repo})" != "" ] && ! ove_git_config_check; then
			ove_echo_error_noprefix "not possible to 'git pull ${repo}' as git config user.email/user.name is not set"
			return 1
		fi

		ove_echo_yellow_noprefix "${repo}"
		if ! ALLOW_OVERRIDE=1 ove_repo_cmd ${repo_fullpath} pull; then
			ove_echo_error_noprefix "git -C ${repo_fullpath} pull failed"
		fi
	fi
}

# $1  : repo
# $2  : command
# $3..: arg
function ove_repo_cmd {
	local cmd
	local git_cmd
	local git_cmd_opt
	local name
	local i
	local repo
	local rev

	repo=$1
	git_cmd="${2##* }"
	if [ "${git_cmd}" != "clone" ] && [ "${git_cmd}" != "ls-remote" ] && [ ! -e ${repo}/.git ]; then
		return 1
	fi

	i=$(ove_repo2index ${repo})
	shift

	if [ "${ALLOW_OVERRIDE}" != "" ] && [ "${ALLOW_OVERRIDE}" = "1" ]; then
		if [ "$i" = "${OVE_OWEL_NAME}" ]; then
			# get rid of some dots
			name=${OVE_OWEL_NAME//\./}
		else
			name=${ove_revtab_git_name[${i}]}
		fi

		if declare -p ove_revtab_git_cmd_opts &>/dev/null; then
			if [ "${ove_revtab_git_cmd_opts["${name}:${git_cmd}"]}" != "" ]; then
				git_cmd_opt="${ove_revtab_git_cmd_opts["${name}:${git_cmd}"]}"
			elif [ "${ove_revtab_git_cmd_opts["*:${git_cmd}"]}" != "" ]; then
				git_cmd_opt="${ove_revtab_git_cmd_opts["*:${git_cmd}"]}"
			fi
		fi
	fi

	if [[ "$git_cmd_opt" == *\$revision* ]]; then
		rev=${ove_revtab_rev[${i}]}
		# replace revision
		git_cmd_opt="${git_cmd_opt/\$revision/$rev}"
	fi

	# construct the git command
	if [ "${git_cmd}" = "clone" ] || [ "${git_cmd}" = "ls-remote" ]; then
		cmd="${ove_cmd2pathname["git"]:?} $1 ${git_cmd_opt}"
	else
		cmd="${ove_cmd2pathname["git"]:?} -C ${repo} $1 ${git_cmd_opt}"

		# dry run?
		if [ "${GIT_DRY_RUN}" != "" ] && [ "${GIT_DRY_RUN}" = "1" ]; then
			cmd+=" --dry-run"
		fi
	fi
	shift

	# run the git command
	if [ "$OVE_GIT_USE_FLOCK" -eq 1 ]; then
		if [ $# -eq 0 ]; then
			GIT_CEILING_DIRECTORIES="${OVE_BASE_DIR}" ${ove_cmd2pathname["flock"]:?} ${OVE_FLOCK_OPTIONS} -x "${OVE_OWEL_TMP_DIR}/.${i}.lock" -c "${cmd}"
		else
			GIT_CEILING_DIRECTORIES="${OVE_BASE_DIR}" ${ove_cmd2pathname["flock"]:?} ${OVE_FLOCK_OPTIONS} -x "${OVE_OWEL_TMP_DIR}/.${i}.lock" -c "${cmd} $(printf -- ' "%s"' "${@}")"
		fi
	else
		if [ $# -eq 0 ]; then
			eval "${cmd}"
		else
			eval "${cmd} $(printf -- ' "%s"' "${@}")"
		fi
	fi
	return $?
}

function ove_revtab_fetch_helper {
	ove_revtab_forsome_parallel "ALLOW_OVERRIDE=1 ove_repo_cmd \${repo} fetch |& ${ove_cmd2pathname["sed"]:?} -e \"s|^|\${i}\$(printf \"%0.s \" \$(eval echo {1..\$((${OVE_REPO_LIST_WIDTH} - \${#i}))}))|g\"" ${OVE_FETCH_MAX_PARALLEL} "$@"
	return $?
}

# $1: repo name
function ove_repo_is_excluded {
	local o
	local opt
	local re
	local repo

	repo="$1"
	while IFS=';' read -a opt -r; do
		for o in "${opt[@]}"; do
			# remove all ' and "
			o=${o//\'}
			o=${o//\"}
			re=\\b$o\\b
			if [[ "${o}" = ". .. "* ]]; then
				return 0
			elif [[ "${o}" = ".*" ]]; then
				return 0
			elif [[ "${repo}" =~ $re ]]; then
				return 0
			fi
		done
	done <<<"${OVE_FETCH_EXCLUDE}"

	return 1
}

# $*: optional list of repositories
function ove_revtab_fetch {
	declare -a f_list
	local c_list
	local err
	local i
	local name
	local repo
	local repos
	local url

	err=0
	if [ $# -ge 1 ]; then
		repos="$*"
	else
		repos=${OVE_REPO_LIST}
	fi

	for repo in ${repos}; do
		if [ "${repo##*/}" = "${OVE_OWEL_NAME}" ]; then
			name="${OVE_OWEL_NAME}"
			url=$(ove_repo_cmd "${OVE_OWEL_DIR}" config --get remote.origin.url)
		else
			i=${ove_revtab_name2index[${repo/${OVE_BASE_DIR}\//}]}
			name=${ove_revtab_git_name[${i}]}
			url="${ove_revtab_fetch_url[${i}]}"
		fi

		if [ "${url}" = "noremote" ]; then
			:
		elif [ "${url}" = "" ]; then
			:
		elif [ "${OVE_FETCH_EXCLUDE}" != "" ] && ove_repo_is_excluded "$name"; then
			:
		elif [ ! -e "${OVE_BASE_DIR}/${name}/.git" ]; then
			c_list+="${name} "
		else
			f_list+=("${name}")
		fi
	done

	if [ "${c_list}" != "" ]; then
		ove_revtab_clone_and_checkout ${c_list} &
	fi

	ove_revtab_fetch_helper "${f_list[@]}"
	err=$?

	wait

	return $err
}

# $1: dir
function ove_is_base_dir {
	if [[ -L ${1}/ove && -L ${1}/.owel ]]; then
		return 0
	else
		return 1
	fi
}

function ove_get_base_dir {
	local s

	if ! pushd . > /dev/null; then
		return 1
	elif ! s=$(pwd -P); then
		return 1
	fi

	while [ "${s}" != "" ]; do
		if ove_is_base_dir "${s}"; then
			echo "${s}"
			break
		fi
		s=${s%/*}
	done

	if ! popd > /dev/null; then
		return 1
	fi

	# base directory found?
	if [ "${s}" = "" ]; then
		ove_echo_error_noprefix "not in an OVE workspace. Try 'ove cd'"
		return 1

	# First time? Do nothing
	elif [ -z "${OVE_BASE_DIR+x}" ]; then
		:

	# Have we moved to another OVE workspace? source that project
	elif [ "${s}" != "${OVE_BASE_DIR}" ] && [[ $- == *i* ]]; then
		if ! cd ${s}; then
			return 1
		elif ! . ove > /dev/null; then
			return 1
		elif ! cd -; then
			return 1
		fi
	fi
}

function ove_list_projects {
	local p

	if [ -f "${OVE_OWEL_DIR}"/projs ]; then
		p=$(printf '%s ' $(${ove_cmd2pathname["grep"]:?} -o '^[a-zA-Z0-9_]\+' ${OVE_OWEL_DIR}/projs | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?}))
		echo ${p::-1}
	fi
}

# $*: file(s)
function ove_file_md5sum {
	local args

	if [ $# -eq 0 ]; then
		return 1
	elif command -v md5deep > /dev/null; then
		if [ "${HASH_SIZE_THRESHOLD}" != "" ]; then
			args="-i ${HASH_SIZE_THRESHOLD}b"
		fi

		${ove_cmd2pathname["md5deep"]:?} ${args} -s -o f -r "${@}"
	else
		if [ "${HASH_SIZE_THRESHOLD}" != "" ]; then
			args="-size ${HASH_SIZE_THRESHOLD}c"
		fi

		${ove_cmd2pathname["find"]:?} "${@}" ${args} -type f -print0 | ${ove_cmd2pathname["xargs"]:?} -0 ${ove_cmd2pathname["md5sum"]:?}
	fi
}

# $*: file(s)
function ove_file_fingerprint {
	local md5

	if [ $# -eq 0 ]; then
		return 1
	fi

	if [ -n "${OVE_DRY_RUN+x}" ] && [ "${OVE_DRY_RUN}" -eq 1 ]; then
		echo
		return
	fi

	# shellcheck disable=SC2016
	md5=$(ove_file_md5sum "${@}" | \
		${ove_cmd2pathname["awk"]:?} '{print $1}' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["md5sum"]:?})
	echo ${md5%% *}
}

# make:[project[-nodeps]]:build project(s):BUILD
function ove-make {
	ove_entry || return

	local fingerprint_a
	local fingerprint_b
	local i
	local proj
	local stage_dir_updated_by
	local target

	if [ $# -gt 1 ]; then
		ove_command_usage
		return 1
	fi

	target="$1"
	if [[ "$(caller 0)" != *"ove-make"* ]]; then
		if ! ove_build_pre ${target%-nodeps}; then
			return 1
		fi
		trap ove_build_post EXIT
	fi

	# build all?
	if [ $# -eq 0 ]; then
		for proj in ${OVE_BUILD_ORDER}; do
			i=${ove_projects_name2index[${proj}]}

			# does proj have any dependencies?
			if [ "${ove_projects_deps[${i}]}" != "" ]; then
				# check if some of the deps has modified the stage dir
				for dep in ${ove_projects_deps[${i}]}; do
					if [[ "${stage_dir_updated_by}" == *"${dep}"* ]]; then
						if ! ove_projects_cmd "${proj}" clean; then
							return 1
						fi
						break
					fi
				done
			fi

			if [ -e "${OVE_OWEL_DIR}/projects/${proj}/build" ]; then
				if ! ove_projects_cmd "${proj}" build; then
					return 1
				fi
			fi

			if [ -e "${OVE_OWEL_DIR}/projects/${proj}/install" ]; then
				fingerprint_a=$(ove_file_fingerprint ${OVE_STAGE_DIR})
				if ! ove_projects_cmd "${proj}" install; then
					return 1
				fi
				fingerprint_b=$(ove_file_fingerprint ${OVE_STAGE_DIR})

				# remember if project modified the stage dir
				if [ "${fingerprint_a}" != "${fingerprint_b}" ]; then
					stage_dir_updated_by+="${proj} "
				fi
			fi
		done

		return 0
	elif [[ ${target} == *-nodeps ]]; then
		target=${target%-nodeps}
		if ! ove_projects_cmd "${target}" build; then
			return 1
		fi

		if ! ove_projects_cmd "${target}" install; then
			return 1
		fi

		return 0
	fi

	if [[ "$(caller 0)" != *"ove-make"* ]]; then
		# keep track of projects built
		_ove_projects_built=""
	fi

	if ! [[ -v ove_projects_name2index[${target}] ]]; then
		ove_echo_error_noprefix "unknown target '${target}'"
		return 1
	fi

	i=${ove_projects_name2index[${target}]}
	# has deps?
	if [ "${ove_projects_deps[${i}]}" != "" ]; then
		if [ -e "${OVE_OWEL_DIR}/projects/${target}/clean" ]; then
			fingerprint_a=$(ove_file_fingerprint ${OVE_STAGE_DIR})
		fi

		for dep in ${ove_projects_deps[${i}]}; do
			if ! [[ -v ove_projects_name2index[${dep}] ]]; then
				ove_echo_warning_noprefix "project '${dep}' not found, skipping"
				continue
			fi

			# already built? next!
			if [[ "${_ove_projects_built}" == *"${dep}"* ]]; then
				continue
			fi

			if ! ove-make "${dep}"; then
				return 1
			fi
		done

		if [ -e "${OVE_OWEL_DIR}/projects/${target}/clean" ]; then
			fingerprint_b=$(ove_file_fingerprint ${OVE_STAGE_DIR})
			# clean the project if OVE_STAGE_DIR was updated
			if [ "${fingerprint_a}" != "${fingerprint_b}" ]; then
				if ! ove_projects_cmd "${target}" clean; then
					return 1
				fi
			fi
		fi
	fi

	if ! ove_projects_cmd "${target}" build; then
		return 1
	fi

	if ! ove_projects_cmd "${target}" install; then
		return 1
	fi

	# remember projects built
	_ove_projects_built+="${target} "

	# cleanup
	if [[ "$(caller 0)" != *"ove-make"* ]]; then
		unset _ove_projects_built
	fi
}

# list-projects:[project...|tag...]:list projects:CORE
function ove-list-projects {
	ove_entry || return

	local f_basename
	local f
	local p
	local proj_list
	local projects

	if [ $# -eq 0 ]; then
		if [ "${OVE_PROJECT_LIST}" != "" ]; then
			printf "%s\n" ${OVE_PROJECT_LIST}
		fi
		return 0
	fi

	if ! proj_list=$(ove_validate_project_list "$@"); then
		return 1
	fi

	projects="$(ove_get_build_list ${proj_list})"
	for p in ${projects}; do
		# ignore projects without a project directory
		if [ ! -d "${OVE_OWEL_DIR}"/projects/${p} ]; then
			continue
		fi

		ove_echo_cyan_noprefix "${p}"
		for f in bootstrap configure build install clean; do
			if [ ! -x ${OVE_OWEL_DIR}/projects/${p}/${f} ]; then
				continue
			fi
			echo -e "\t${f}"
			${ove_cmd2pathname["sed"]:?} -e 's|^|\t\t|g' <${OVE_OWEL_DIR}/projects/${p}/${f}
		done

		while read -r line; do
			f_basename=${line##*/}
			if [[ "bootstrap configure build install clean" =~ ${f_basename} ]]; then
				continue
			fi
			echo -e "\t${f_basename}"
			${ove_cmd2pathname["sed"]:?} -e 's|^|\t\t|g' <${OVE_OWEL_DIR}/projects/${p}/${f_basename}
		done < <(${ove_cmd2pathname["find"]:?} "${OVE_OWEL_DIR}"/projects/${p} -perm -u=x -type f)
		echo
	done | ${ove_cmd2pathname["head"]:?} -n -1

	return 0
}

# digraph: :create a DOT directed graph for all projects:CORE
function ove-digraph {
	ove_entry || return

	local f
	local i
	local n

	if [ ${ove_number_of_projects} -eq 0 ]; then
		return 0
	fi

	{
		n="${OVE_OWEL_NAME//-/_}"
		n="${n//.}"
		echo "digraph ${n} {"

		i=0
		while ((i < ove_number_of_projects)); do
			if [ "${ove_projects_deps[${i}]}" != "" ]; then
				for d in ${ove_projects_deps[${i}]}; do
					echo "    ${ove_projects_name[${i}]} -> ${d};"
				done
			else
				echo "    ${ove_projects_name[${i}]};"
			fi
			(( i+=1 ))
		done

		echo "}"
	} > ${OVE_OWEL_TMP_DIR}/digraph.dot

	if ! command -v dot > /dev/null; then
		ove_echo_note_noprefix "install 'dot' to render graph as svg, pdf and png" 1>&2
	else
		for f in svg pdf png; do
			if ! ${ove_cmd2pathname["dot"]:?} \
				-T${f} \
				${OVE_OWEL_TMP_DIR}/digraph.dot > ${OVE_OWEL_TMP_DIR}/digraph.${f}; then
				return 1
			fi
		done
	fi

	if ! command -v graph-easy > /dev/null; then
		ove_echo_note_noprefix "install 'graph-easy' to render graph as html, boxart and ascii" 1>&2
	else
		for f in html boxart ascii; do
			if ! ${ove_cmd2pathname["graph-easy"]:?} \
				--from=dot \
				--as=${f} \
				< ${OVE_OWEL_TMP_DIR}/digraph.dot > ${OVE_OWEL_TMP_DIR}/digraph.${f} 2> /dev/null; then
				return 1
			fi
		done
	fi

	if [ -s "${OVE_OWEL_TMP_DIR}/digraph.ascii" ]; then
		${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/digraph.ascii
	fi

	for f in dot svg pdf png html boxart ascii; do
		if [ ! -e "${OVE_OWEL_TMP_DIR}/digraph.${f}" ]; then
			continue
		fi
		${ove_cmd2pathname["du"]:?} -sh "${OVE_OWEL_TMP_DIR}/digraph.${f}" 1>&2
	done

	return 0
}

function ove_build_topology {
	for (( i=0; i < ove_number_of_projects; i++ )) do
		if [ "${ove_projects_deps[${i}]}" = "" ]; then
			continue
		fi

		for d in ${ove_projects_deps[${i}]}; do
			if [[ ! -v ove_projects_name2index[${d}] ]]; then
				continue
			fi
			echo "${ove_projects_name[${i}]} ${d}"
		done
	done | ${ove_cmd2pathname["tsort"]:?} | ${ove_cmd2pathname["tac"]:?}
}

# build-order: :show build order:BUILD
function ove-build-order {
	ove_entry || return

	local autonomous_projs
	local topology

	if [ ${ove_number_of_projects} -eq 0 ]; then
		return
	fi

	# just a bunch of projects without deps?
	if [ "$(ove_list_projects_with_deps)" = "" ]; then
		ove_list_projects_without_deps
		return
	fi

	topology=$(ove_build_topology)
	autonomous_projs=$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -3 \
		<(printf "%s\n" ${OVE_PROJECT_LIST}) \
		<(printf "%s\n" ${topology} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}))

	echo ${autonomous_projs} ${topology}
}

# forowel:command:run 'command' for all OVE workspaces on this host:CORE
function ove-forowel {
	ove_entry || return

	local cmd
	local i
	local projs

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	i=0
	mapfile -t projs < <(ove_list_workspaces_full)
	while ((i < ${#projs[@]})); do
		cmd+=$(printf "
			echo '# %s'
			cd %s
			ove_init
			$*
			" $(ove_echo_green_noprefix ${projs[i]##*/}) ${projs[i]})
		(( i+=1 ))
	done
	eval "${cmd}"
}

# forowel-parallel:command:run 'command' in parallel for all OVE workspaces on this host:CORE
function ove-forowel-parallel {
	ove_entry || return

	local cmd
	local i
	local projs

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	i=0
	mapfile -t projs < <(ove_list_workspaces_full)
	while ((i < ${#projs[@]})); do
		cmd=$(printf "
			cd %s
			ove_init
			$*
			" ${projs[i]})
		(( i+=1 ))
		{
			eval "${cmd}"
		} &
	done
	wait
}

# forall:command:run 'command' for all git repositories:CORE
function ove-forall {
	ove_entry || return

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	ove_revtab_forall "$*"
}

# forall-parallel:command:run 'command' in parallel for all git repositories:CORE
function ove-forall-parallel {
	ove_entry || return

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	ove_revtab_forall_parallel "$*"
}

# forsome:command git...:run 'command' for specified git repositories:CORE
function ove-forsome {
	ove_entry || return

	if [ $# -lt 2 ]; then
		ove_command_usage
		return 1
	fi

	ove_revtab_forsome "$1" "${@:2}"
}

# list systest groups helper
function ove_list_systests_groups {
	if [ -e ${OVE_OWEL_DIR}/systests-groups ]; then
		${ove_cmd2pathname["grep"]:?} : "${OVE_OWEL_DIR}"/systests-groups | \
			${ove_cmd2pathname["sed"]:?} -e 's,[[:space:]],,g' -e 's,^-,,g' -e 's,:$,,g'
	fi
}

# list-systests: :list available system tests:TEST
function ove-list-systests {
	ove_entry || return

	if [ ! -e ${OVE_OWEL_DIR}/systests ]; then
		return
	fi
	(
	# shellcheck disable=SC2016
	${ove_cmd2pathname["grep"]:?} -E -v '^$|^\s*#|.*:|^#.*' "${OVE_OWEL_DIR}"/systests | \
		${ove_cmd2pathname["awk"]:?} '{print $1}'
	ove-list-systests-aliases
	ove_list_systests_groups
	) | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

# list-systests-aliases: :list available system test aliases:TEST
function ove-list-systests-aliases {
	ove_entry || return

	if [ ! -e ${OVE_OWEL_DIR}/systests ]; then
		return
	fi

	# shellcheck disable=SC2016
	${ove_cmd2pathname["awk"]:?} '{print $1}' "${OVE_OWEL_DIR}"/systests | \
		${ove_cmd2pathname["grep"]:?} : | \
		${ove_cmd2pathname["grep"]:?} -v '#' | \
		${ove_cmd2pathname["cut"]:?} -d: -f1 | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

# hooks:[disable|enable|install|remove [hook]|list]:manage hooks:CORE
function ove-hooks {
	ove_entry || return

	local args
	local h
	local i

	if [ $# -eq 0 ]; then
		cmd="list"
	else
		cmd="$1"
	fi

	if [ "${cmd}" = "list" ]; then
		if [ ! -d ${OVE_DIR}/hooks ]; then
			return 0
		fi

		echo "available:"
		while read -r h; do
			echo "  ${h##*/}"
			while read -r i; do
				echo "    ${i##*/}"
			done <<<$(${ove_cmd2pathname["find"]:?} ${h} -type f)
		done <<<$(${ove_cmd2pathname["find"]:?} "${OVE_DIR}/hooks" -maxdepth 1 -mindepth 1)
		if [ -d "${OVE_OWEL_DIR}/hooks" ]; then
			h=$(ove-list-hooks enabled)
			i=$(ove-list-hooks disabled)
			if [ "${h}" != "" ] || [ "${i}" != "" ]; then
				echo "installed:"
				if [ "${h}" != "" ]; then
					echo "  enabled:"
					printf "%s\n" "${h}" | ${ove_cmd2pathname["sed"]:?} -e 's,^,    ,g'
				fi
				if [ "${i}" != "" ]; then
					echo "  disabled:"
					printf "%s\n" "${i}" | ${ove_cmd2pathname["sed"]:?} -e 's,^,    ,g'
				fi
			fi
		fi
	elif [ "${cmd}" = "disable" ] || [ "${cmd}" = "enable" ] || [ "${cmd}" = "remove" ]; then
		if [ $# -eq 2 ]; then
			h="$2"
		else
			if ! read -r -p "hook: "; then
				return 1
			fi
			h="$REPLY"
			if [ "$h" = "" ]; then
				return 1
			fi
		fi

		# relative hook?
		if [ -f "${OVE_OWEL_DIR}/hooks/${h}" ]; then
			h="${OVE_OWEL_DIR}/hooks/${h}"
		# absolute hook?
		elif [[ "$h" = "${OVE_OWEL_DIR}/hooks/"* ]] && [ -f "${h}" ]; then
			true
		# hook dir?
		elif [ -d "${OVE_OWEL_DIR}/hooks/${h}" ]; then
			h="${OVE_OWEL_DIR}/hooks/${h}"
		else
			ove_echo_error_noprefix "hook '${h}' is not installed"
			return 1
		fi

		while read -r i; do
			if [ "${cmd}" = "remove" ]; then
				${ove_cmd2pathname["rm"]:?} "${i}"
				continue
			elif [ "${cmd}" = "disable" ]; then
				args="-x"
			else
				args="+x"
			fi
			${ove_cmd2pathname["chmod"]:?} ${args} "${i}"
		done <<<$(${ove_cmd2pathname["find"]:?} "${h}" -maxdepth 1 -type f)
		if [ "${cmd}" = "remove" ]; then
			if [ -e "${h}" ]; then
				${ove_cmd2pathname["rm"]:?} -rf "${h}"
			fi
		fi
	elif [ "${cmd}" = "install" ]; then
		if [ $# -eq 2 ]; then
			h="$2"
		else
			if ! read -r -p "hook: "; then
				return 1
			fi
			h="$REPLY"
			if [ "$h" = "" ]; then
				return 1
			fi
		fi

		# hook dir?
		if [ -d "${OVE_DIR}/hooks/${h}" ]; then
			h="${OVE_DIR}/hooks/${h}"
			if ! ${ove_cmd2pathname["mkdir"]:?} -p "${OVE_OWEL_DIR}/hooks"; then
				return 1
			fi
		else
			ove_echo_error_noprefix "hook '${h}' not found"
			return 1
		fi

		if ! ${ove_cmd2pathname["cp"]:?} -a "${h}" "${OVE_OWEL_DIR}/hooks"; then
			return 1
		fi
	else
		ove_command_usage
		return 1
	fi
}

# list-hooks:[enabled|disabled]:list installed hooks:CORE
function ove-list-hooks {
	ove_entry || return

	local opt
	local p
	local repo

	if [ $# -eq 1 ]; then
		if [ "$1" = "disabled" ]; then
			opt="-not"
		elif [ "$1" = "enabled" ]; then
			true
		else
			ove_command_usage
			return 1
		fi
	fi

	# project hooks
	if [ -d "${OVE_OWEL_DIR}/hooks" ]; then
		p+="${OVE_OWEL_DIR}/hooks "
	fi

	# repo hooks
	for repo in $(ove_revtab_list_fullpath); do
		if ! [ -d "${repo}/.ove/hooks" ]; then
			continue
		fi
		p+="${repo}/.ove/hooks "
	done

	if [ "${p}" != "" ]; then
		${ove_cmd2pathname["find"]:?} -L ${p} ${opt} -perm -u=x -type f -not -size 0 | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
	fi

	return 0
}

# list-scripts: :list available scripts:CORE
function ove-list-scripts {
	ove_entry || return

	local p
	local repo

	while true; do
		# OWEL scripts
		if [ -d "${OVE_OWEL_DIR}/scripts" ]; then
			${ove_cmd2pathname["find"]:?} ${OVE_OWEL_DIR}/scripts -perm -u=x -not -name '*.help' -type f
		fi

		# repo scripts
		for repo in $(ove_revtab_list_fullpath); do
			if [ ! -d "${repo}/.ove/scripts" ]; then
				continue
			fi
			p+="${repo}/.ove/scripts "
		done
		if [ "${p}" != "" ]; then
			${ove_cmd2pathname["find"]:?} -L ${p} -perm -u=x -not -name '*.help' -type f
		fi

		break
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}

	return 0
}

function ove_list_scripts_directories {
	local d
	local repo

	# OWEL scripts
	if [ -d "${OVE_OWEL_DIR}/scripts" ]; then
		d+="${OVE_OWEL_DIR}/scripts "
	fi
	# repo scripts
	for repo in ${OVE_REPO_LIST}; do
		if [ ! -d "${repo}/.ove/scripts" ]; then
			continue
		fi
		d+="${repo}/.ove/scripts "
	done

	if [ "${d}" = "" ]; then
		return
	fi

	${ove_cmd2pathname["find"]:?} -L ${d} -perm -u=x -not -name '*.help' -type f -print0 | \
		${ove_cmd2pathname["xargs"]:?} -0 dirname 2> /dev/null | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
}

# $1: str
# $2: res
function ove_time_pad {
	local i=0
	local o="$1"
	local -n res="$2"
	local z

	z=$((OVE_TIME_GRANULARITY - ${#1}))
	while [ $i -lt $z ]; do
		o="0$o"
		i=$((i + 1))
	done
	res="$o"
}

# $1: sec
# $2: frac
function ove_time_diff {
	local now="${EPOCHREALTIME}"

	if [ "${now}" = "" ]; then
		now=$(${ove_cmd2pathname["date"]:?} +%s${OVE_TIME_SEPARATOR}%N)
	fi
	now_s=${now%"${OVE_TIME_SEPARATOR}"*}
	now_f=${now#*"${OVE_TIME_SEPARATOR}"}

	# remove leading zeros
	now_f=$((10#${now_f}))

	# exit early?
	if [ "${1}" = "" ]; then
		diff="00:00:00"
		diff_f=$(eval printf '0%.0s' "{1..$OVE_TIME_GRANULARITY}")
		return
	fi

	local diff_s=$((now_s - $1))
	diff_f="$((now_f - $2))"
	if [ "${diff_f}" -lt 0 ]; then
		(( diff_s-=1 )) || true
		diff_f="$((10**OVE_TIME_GRANULARITY + diff_f))"
	fi

	if [ $diff_s -lt 10 ]; then
		diff="00:00:0$diff_s"
	elif [ $diff_s -lt 60 ]; then
		diff="00:00:$diff_s"
	else
		# shellcheck disable=SC2016
		diff="$(${ove_cmd2pathname["awk"]:?} '{printf "%02d:%02d:%02d\n", int($1/3600),int(($1%3600)/60),int($1%60)}' <<<"${diff_s}")"
	fi
}

function ove_echo {
	local a
	local b
	local diff
	local diff_f
	local now_f
	local now_s

	ove_time_diff "${OVE_PREV_S}" "${OVE_PREV_F}"
	ove_time_pad "${now_f}" a
	ove_time_pad "${diff_f}" b

	OVE_PREV_S=${now_s}
	OVE_PREV_F=${now_f}

	printf "%(%Y-%m-%d %H:%M:%S)T.%s (+%s:%s):%s\n" \
		"$now_s" \
		"${a}" \
		"${diff}" \
		"${b}" \
		"$(echo -e "$*")"
}

function ove_time {
	local b
	local diff
	local diff_f
	local now_f
	local now_s

	ove_time_diff "${OVE_TIME_S}" "${OVE_TIME_F}"
	ove_time_pad "${diff_f}" b

	OVE_TIME_S=${now_s}
	OVE_TIME_F=${now_f}

	printf "%s:%s\n" "$diff" "$b"
}

# echo:[green|cyan|yellow|red|error] txt:prefix echo with date and time diff:CORE
function ove-echo {
	ove_entry || return

	local f

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	if [ "$(type -t ove_echo_$1)" = "function" ]; then
		if [ $# -eq 1 ]; then
			ove_command_usage
			return 1
		fi
		f="ove_echo_$1"
		shift
		$f "$@"
	else
		ove_echo "$@"
	fi
}

# list-colors: :list OVE colors:CORE
function ove-list-colors {
	local c
	local j
	local s
	local v

	for c in green yellow red cyan blue; do
		v="OVE_COLOR_${c^^}"
		echo "$c ${!v}"
		s=
		for j in $(${ove_cmd2pathname["seq"]:?} 1 $((OVE_COLUMNS/2))); do
			if [ $((j%3)) -eq 0 ]; then
				s+="E "
			elif [ $((j%3)) -eq 1 ]; then
				s+="O "
			elif [ $((j%3)) -eq 2 ]; then
				s+="V "
			fi
		done
		ove_echo_${c}_noprefix "$s"
	done
}

function ove_echo_cyan {
	ove_echo "${OVE_COLOR_CYAN}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_cyan_error {
	ove_echo "${OVE_COLOR_CYAN}""$*""${OVE_COLOR_BLANK}" 1>&2;
}

function ove_echo_cyan_error_noprefix {
	echo -e "${OVE_COLOR_CYAN}""$*""${OVE_COLOR_BLANK}" 1>&2;
}

function ove_echo_yellow {
	ove_echo "${OVE_COLOR_YELLOW}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_blue {
	ove_echo "${OVE_COLOR_BLUE}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_green {
	ove_echo "${OVE_COLOR_GREEN}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_green_noprefix {
	echo -e "${OVE_COLOR_GREEN}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_red {
	ove_echo "${OVE_COLOR_RED}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_red_noprefix {
	echo -e "${OVE_COLOR_RED}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_yellow_noprefix {
	echo -e "${OVE_COLOR_YELLOW}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_blue_noprefix {
	echo -e "${OVE_COLOR_BLUE}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_warning {
	ove_echo_yellow "warning: $*" 1>&2;
}

function ove_echo_cyan_noprefix {
	echo -e "${OVE_COLOR_CYAN}""$*""${OVE_COLOR_BLANK}"
}

function ove_echo_note_noprefix {
	echo -e "${OVE_COLOR_CYAN}NOTE:${OVE_COLOR_BLANK} $*"
}

function ove_echo_error {
	ove_echo_red "error: $*" 1>&2;
}

function ove_echo_error_noprefix {
	ove_echo_red_noprefix "error: $*" 1>&2;
}

function ove_echo_fatal_noprefix {
	ove_echo_red_noprefix "fatal: $*" 1>&2;
}

function ove_echo_warning_noprefix {
	ove_echo_yellow_noprefix "warning: $*" 1>&2;
}

function ove_echo_stderr {
	ove_echo "$@" 1>&2;
}

function ove_echo_stderr_noprefix {
	echo "$@" 1>&2;
}

function ove_command_not_found {
	local msg="command '$1' not found"

	if [ $# -eq 2 ]; then
		msg+=". $2"
	fi
	ove_echo_error_noprefix "${msg}"
}

function ove_check_command {
	if ! command -v "$1" > /dev/null; then
		ove_command_not_found "$1"
		return 1
	elif [ "${ove_cmd2pathname["$1"]}" = "" ]; then
		ove_externals_reinit
	fi

	return 0
}

function ove_systest_get_exit_status {
	local e

	if [ $# -eq 0 ]; then
		e="NA"
	elif [ ${1} -eq 124 ]; then
		e="TIMEOUT"
	elif [ ${1} -eq 126 ]; then
		e="PERMISSION_DENIED"
	elif [ ${1} -eq 127 ]; then
		e="CAN_NOT_FIND_CMD"
	elif [ ${1} -gt 128 ] && [ ${1} -lt 166 ]; then
		e="SIG$(kill -l ${1})"
	elif [ -e /usr/include/sysexits.h ] && \
		${ove_cmd2pathname["grep"]:?} -q "#define EX_[A-Z]\+.*\b${1}\b" /usr/include/sysexits.h; then
		e=$(${ove_cmd2pathname["grep"]:?} "#define EX_[A-Z]\+.*\b${1}\b" /usr/include/sysexits.h | \
			${ove_cmd2pathname["grep"]:?} -o 'EX_[A-Z]\+')
	elif [ -e ${OVE_OWEL_DIR}/${OVE_OWEL_NAME}-sysexits.h ] && \
		${ove_cmd2pathname["grep"]:?} -q "#define [A-Z0-9_]\+.*\b${1}$" ${OVE_OWEL_DIR}/${OVE_OWEL_NAME}-sysexits.h; then
		e=$(${ove_cmd2pathname["grep"]:?} "#define [A-Z0-9_]\+.*\b${1}$" ${OVE_OWEL_DIR}/${OVE_OWEL_NAME}-sysexits.h | \
			${ove_cmd2pathname["cut"]:?} -f1 | \
			${ove_cmd2pathname["cut"]:?} -d' ' -f2)

	else
		e="${1}"
	fi

	echo "${e}"
}

function ove_systest_cleanup {
	${ove_cmd2pathname["ps"]:?} -o pid= -s $$ | \
		${ove_cmd2pathname["grep"]:?} -v "$$" > $OVE_TMP/systest-pids
	if [ -s $OVE_TMP/systest-pids ]; then
		ove_kill_procs 1 0.1 $(${ove_cmd2pathname["cat"]:?} $OVE_TMP/systest-pids)
	fi
	${ove_cmd2pathname["rm"]:?} $OVE_TMP/systest-pids
}

function ove_systest_print_summary {
	local str
	local t

	for t in ${!systest2exit[*]}; do
		if [ ${systest2exit[$t]} -eq -3 ]; then
			printf "ove-systest:%03d:%03d:${OVE_COLOR_RED}AB${OVE_COLOR_BLANK}:${systest2duration[$t]}:${systest2name[$t]}:ABORT\n" ${t} ${nbr_of_systests}
		elif [ ${systest2exit[$t]} -eq -2 ]; then
			printf "ove-systest:%03d:%03d:${OVE_COLOR_YELLOW}KO${OVE_COLOR_BLANK}:${systest2duration[$t]}:${systest2name[$t]}:ENV\n" ${t} ${nbr_of_systests}
		elif [ ${systest2exit[$t]} -eq -1 ]; then
			s=${systest2duration[$t]%%:*}
			f=${systest2duration[$t]##*:}
			printf "ove-systest:%03d:%03d:${OVE_COLOR_BLUE}BG${OVE_COLOR_BLANK}:$(OVE_TIME_S=$s OVE_TIME_F=$f ove_time):${systest2name[$t]}:?\n" ${t} ${nbr_of_systests}
		elif [ ${systest2exit[$t]} -eq 0 ]; then
			printf "ove-systest:%03d:%03d:${OVE_COLOR_GREEN}OK${OVE_COLOR_BLANK}:${systest2duration[$t]}:${systest2name[$t]}:0\n" ${t} ${nbr_of_systests}
		else
			str=$(ove_systest_get_exit_status ${systest2exit[$t]})
			printf "ove-systest:%03d:%03d:${OVE_COLOR_YELLOW}KO${OVE_COLOR_BLANK}:${systest2duration[$t]}:${systest2name[$t]}:${str}\n" ${t} ${nbr_of_systests}
		fi
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -n
	echo
}

# systest:[test|group...]:run one or more system tests/groups described in ${OVE_OWEL_DIR}/systests-groups and ${OVE_OWEL_DIR}/systests:TEST
function ove-systest {
	ove_entry || return

	local all_done
	local exit_status
	local groups
	local i
	local match
	local nbr_of_systests
	local q
	local systest_alias
	local systest_bg
	local systest_cmd
	local systest_list
	local systest_list_tmp
	local systest_name
	local systest_path
	local systest_row
	local systest_timeout
	local systest_type
	local t
	local timeout_cmd
	local u

	if [ ! -e ${OVE_OWEL_DIR}/systests ]; then
		return 1
	elif [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	if ! [ -e ${OVE_OWEL_DIR}/systests-groups ]; then
		systest_list="$*"
	else
		groups=$(ove_list_systests_groups | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})

		if [ "${groups}" = "" ]; then
			systest_list="$*"
		elif ! command -v python3 > /dev/null; then
			ove_echo_yellow_noprefix "python3 not found, not possible to launch 'yex'"
			systest_list="$*"
		else
			for systest_name in "$@"; do
				if ${ove_cmd2pathname["grep"]:?} -w -q ${systest_name} <<<"${groups}"; then
					systest_list+=" $(${OVE_DIR}/yex ${OVE_OWEL_DIR}/systests-groups -s -r --groups "${systest_name}")"
				else
					systest_list+=" ${systest_name}"
				fi
			done
		fi
	fi

	if [ "${systest_list}" = "" ]; then
		echo "error: no tests found" 1>&2
		return 1
	fi

	# repeat?
	if [ -n "${OVE_SYSTEST_REPEAT+x}" ] && \
		[ "${OVE_SYSTEST_REPEAT}" -gt 1 ]; then

		for systest_name in ${systest_list}; do
			for q in $(${ove_cmd2pathname["seq"]:?} 1 ${OVE_SYSTEST_REPEAT}); do
				systest_list_tmp+=" ${systest_name}"
			done
		done

		systest_list=${systest_list_tmp}
	fi

	# skip tests
	if [ -n "${OVE_SYSTEST_SKIP+x}" ]; then
		# skip every X:th test?
		if [[ "${OVE_SYSTEST_SKIP}" =~ ^[0-9]+$ ]]; then
			if [ "${OVE_SYSTEST_SKIP}" -gt 1 ]; then
				i=0
				for systest_name in ${systest_list}; do
					if (( i % OVE_SYSTEST_SKIP == 0 )); then
						systest_list_tmp+=" ${systest_name}"
					fi
					(( i=i+1 ))
				done

				systest_list=${systest_list_tmp}
			fi
		else
			# skip specific tests
			systest_list=$(printf "%s\n" ${systest_list} | \
				${ove_cmd2pathname["grep"]:?} -v -f <(printf "%s\n" $OVE_SYSTEST_SKIP))
			if [ "${systest_list}" = "" ]; then
				echo "error: everything skipped, check config 'OVE_SYSTEST_SKIP'" 1>&2
				return 1
			fi
		fi
	fi

	nbr_of_systests=$(${ove_cmd2pathname["wc"]:?} -w <<<"${systest_list}")
	if [ ${nbr_of_systests} -gt 1 ]; then
		echo "${FUNCNAME[0]}:Will run ${nbr_of_systests} test cases:"
		i=0
		for systest_name in ${systest_list}; do
			(( i=i+1 ))
			printf "${FUNCNAME[0]}:%03d:%03d:${systest_name}\n" ${i} ${nbr_of_systests}
		done
		echo
	fi

	# trap SIGINT to allow user to press CTRL+C
	trap true SIGINT

	i=0
	declare -A pids_db=()
	declare -a systest2name=()
	declare -a systest2abort=()
	declare -A systest2exit=()
	declare -A systest2duration=()
	for systest_name in ${systest_list}; do
		(( i=i+1 ))

		# alias?
		match=$(${ove_cmd2pathname["grep"]:?} -c ^${systest_name}: "${OVE_OWEL_DIR}"/systests)
		if [ ${match} -eq 1 ]; then
			systest_alias="${systest_name}"
			systest_name=$(${ove_cmd2pathname["grep"]:?} ^${systest_name}: "${OVE_OWEL_DIR}"/systests | \
				${ove_cmd2pathname["cut"]:?} -d: -f2)

			if [ "${systest_name}" = "" ]; then
				ove_echo_error_noprefix "${FUNCNAME[0]}:alias '${systest_alias}' points to an empty systest"
				systest2exit[$i]=-2
				continue
			fi
		fi

		match=$(${ove_cmd2pathname["grep"]:?} -c -w ^${systest_name} "${OVE_OWEL_DIR}"/systests)
		if [ ${match} -eq 0 ]; then
			ove_echo_error_noprefix "${FUNCNAME[0]}:can not find systest '${systest_name}'"
			systest2exit[$i]=-2
			continue
		elif [ ${match} -gt 1 ]; then
			ove_echo_error_noprefix "${FUNCNAME[0]}:${match} match(es) for '${systest_name}'"
			${ove_cmd2pathname["grep"]:?} ^${systest_name} "${OVE_OWEL_DIR}"/systests
			systest2exit[$i]=-2
			continue
		fi

		read -r -a systest_row <<<"$(${ove_cmd2pathname["grep"]:?} -w ^${systest_name} "${OVE_OWEL_DIR}"/systests)"
		systest_name=${systest_row[0]}
		systest_timeout=${systest_row[1]}
		systest_type=${systest_row[2]}
		systest2name[i]="${systest_name}"
		systest2abort[i]=$(((systest_type & 0x1) != 0))
		systest_bg=$(((systest_type & 0x2) != 0))

		systest_path=${systest_row[3]//\"}
		systest_path=$(eval echo ${systest_path})
		if [ "${systest_path}" = "" ]; then
			ove_echo_error_noprefix "none valid path for systest '${systest_name}'"
			systest2exit[$i]=-2
			continue
		fi

		if [ "${systest_path:0:1}" = "/" ]; then
			# abs path
			if ! [ -d "${systest_path}" ]; then
				ove_echo_error_noprefix "path '${systest_path}' not found for systest '${systest_name}'"
				systest2exit[$i]=-2
				continue
			fi
		else
			# rel path
			if ! [ -d "${OVE_BASE_DIR}/${systest_path}" ]; then
				ove_echo_error_noprefix "path '${OVE_BASE_DIR}/${systest_path}' not found for systest '${systest_name}'"
				systest2exit[$i]=-2
				continue
			fi
			systest_path="${OVE_BASE_DIR}/${systest_path}"
		fi
		systest_cmd=${systest_row[*]:4}
		systest_cmd=${systest_cmd//\"}

		if ! pushd "${systest_path}" &> /dev/null; then
			ove_echo_error_noprefix "'pushd ${systest_path}' failed for systest '${systest_name}'"
			systest2exit[$i]=-2
			continue
		fi

		if [ "${OVE_SYSTEST_HEADER}" = "short" ]; then
			printf "${FUNCNAME[0]}:%03d:%03d:${systest_name}\n" ${i} ${nbr_of_systests}
		elif [ "${OVE_SYSTEST_HEADER}" = "detailed" ]; then
			printf "%s:%03d:%03d:name: %s timeout: %s type: %s path: %s cmd: %s\n" \
				"${FUNCNAME[0]}" \
				"${i}" \
				"${nbr_of_systests}" \
				"${systest_name}" \
				"${systest_timeout}" \
				"${systest_type}" \
				"${systest_path}" \
				"${systest_cmd}"
		elif [ "${OVE_SYSTEST_HEADER}" = "off" ]; then
			true
		else
			ove_echo_error_noprefix "invalid value for OVE_SYSTEST_HEADER, try: $(ove_config_get_allowed OVE_SYSTEST_HEADER)"
			return 1
		fi

		OVE_SYSTEST_ACTIVE_TEST_CASE=${systest_name}
		export OVE_SYSTEST_ACTIVE_TEST_CASE

		OVE_SYSTEST_ITERATION=${i}
		export OVE_SYSTEST_ITERATION

		OVE_SYSTEST_NBR_TESTS=${nbr_of_systests}
		export OVE_SYSTEST_NBR_TESTS

		if [ "${OVE_DRY_RUN}" -eq 1 ]; then
			# dry run
			systest2exit[$i]=0
			systest2duration[$i]="00:00:00"
		else
			if [ ${systest_timeout} -eq 0 ]; then
				timeout_cmd=""
			else
				timeout_cmd="timeout --foreground --kill-after 30s ${systest_timeout}"
			fi

			ove_time > /dev/null
			# run the systest as a background job
			if [ ${systest_bg} -eq 1 ]; then
				${timeout_cmd} ${ove_cmd2pathname["bash"]:?} -c "{ ${systest_cmd}; }" &
				pids_db[${i}]=${!}
				systest2exit[$i]=-1
				systest2duration[$i]="${OVE_TIME_S}:${OVE_TIME_F}"
			# run in fg
			elif ${timeout_cmd} ${ove_cmd2pathname["bash"]:?} -c "{ ${systest_cmd}; }"; then
				# test passed
				systest2exit[$i]=0
				systest2duration[$i]="$(ove_time)"
			else
				systest2exit[$i]=${?}
				systest2duration[$i]="$(ove_time)"
				# type 1 systest or SIGINT => stop loop
				if [ ${systest_type} -eq 1 ] || [ ${systest2exit[$i]} -eq 130 ]; then
					if ! popd &> /dev/null; then
						ove_echo_fatal_noprefix "'popd' failed"
						return 1
					fi
					break
				fi
			fi

			if [ $OVE_SYSTEST_CLEANUP -eq 1 ] && command -v ps > /dev/null; then
				ove_systest_cleanup
			fi
		fi

		ove_systest_print_summary
		if ! popd &> /dev/null; then
			ove_echo_fatal_noprefix "'popd' failed"
			return 1
		fi
	done

	while true; do
		all_done=1
		for t in ${!pids_db[*]}; do
			if [ ${pids_db[$t]} -eq 0 ]; then
				continue
			elif kill -0 ${pids_db[$t]} 2> /dev/null; then
				all_done=0
			else
				# get and remember the exit status
				wait ${pids_db[$t]}
				systest2exit[$t]=${?}
				s=${systest2duration[$t]%%:*}
				f=${systest2duration[$t]##*:}
				systest2duration[$t]="$(OVE_TIME_S=$s OVE_TIME_F=$f ove_time)"

				# abort on errors?
				if [ ${systest2exit[$t]} -ne 0 ] && [ ${systest2abort[$t]} -eq 1 ]; then
					if command -v ps > /dev/null; then
						ove_systest_cleanup
					fi
					for u in ${!systest2exit[*]}; do
						# mark BG jobs as ABT
						if [ ${systest2exit[$u]} -eq -1 ]; then
							systest2exit[$u]=-3
							s=${systest2duration[$u]%%:*}
							f=${systest2duration[$u]##*:}
							systest2duration[$u]="$(OVE_TIME_S=$s OVE_TIME_F=$f ove_time)"
						fi
					done
					break 2
				fi
				ove_systest_print_summary
				pids_db[$t]=0
			fi
		done

		if [ $all_done -eq 1 ]; then
			break
		fi

		${ove_cmd2pathname["sleep"]:?} 0.1
	done

	echo
	if [ ${nbr_of_systests} -gt 1 ]; then
		echo ${FUNCNAME[0]}:Summary:
		ove_systest_print_summary
	fi

	if [ "${OVE_LAST_COMMAND}" != "" ]; then
		echo "OVE log: ${OVE_LAST_COMMAND}"
	fi

	# last failed test => exit status
	exit_status=0
	for u in ${!systest2exit[*]}; do
		if [ ${systest2exit[$u]} != 0 ]; then
			exit_status=${systest2exit[$u]}
		fi
	done

	return ${exit_status}
}

# helper function for a few revtab functions below
function ove_revtab_sanity_check {
	if [ $# -ne 2 ]; then
		ove_echo_error_noprefix "please provide two revisions for '${OVE_OWEL_DIR}'"
		return 1
	fi

	if [ "$1" = "$2" ]; then
		ove_echo_error_noprefix "please provide two different revisions for '${OVE_OWEL_DIR}'"
		return 1
	fi

	if ! ove_repo_cmd "${OVE_OWEL_DIR}" cat-file -e "$1" &> /dev/null; then
		ove_echo_error_noprefix "'$1' is not a valid revision"
		return 1
	fi

	if ! ove_repo_cmd "${OVE_OWEL_DIR}" cat-file -e "$2" &> /dev/null; then
		ove_echo_error_noprefix "'$2' is not a valid revision"
		return 1
	fi

	if ! ove_repo_cmd "${OVE_OWEL_DIR}" " --no-pager show" $1:revtab &> /dev/null; then
		ove_echo_error_noprefix "revtab for '$1' is not available"
		return 1
	fi

	if ! ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager show" $2:revtab &> /dev/null; then
		ove_echo_error_noprefix "revtab for '$2' is not available"
		return 1
	fi
}

# revtab-diff:<rev> <rev>:print changes between two project revisions:CORE
function ove-revtab-diff {
	ove_entry || return

	local a
	local b
	local r
	local sha_1
	local sha_2

	if ! ove_revtab_sanity_check "$@"; then
		ove_command_usage
		return 1
	fi

	# save revtab for rev A and rev B
	a=$(ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager show" $1:revtab | \
		${ove_cmd2pathname["grep"]:?} -v \# | \
		${ove_cmd2pathname["xargs"]:?} -n4)
	b=$(ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager show" $2:revtab | \
		${ove_cmd2pathname["grep"]:?} -v \# | \
		${ove_cmd2pathname["xargs"]:?} -n4)

	# extract repo
	# shellcheck disable=SC2016
	printf "${a}" | \
		${ove_cmd2pathname["awk"]:?} '{print $1}' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} > ${OVE_OWEL_TMP_DIR}/repos_A
	# shellcheck disable=SC2016
	printf "${b}" | \
		${ove_cmd2pathname["awk"]:?} '{print $1}' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} > ${OVE_OWEL_TMP_DIR}/repos_B

	# extract repo/rev
	# shellcheck disable=SC2016
	printf "${a}" | \
		${ove_cmd2pathname["awk"]:?} '{print $1,$4}' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} > ${OVE_OWEL_TMP_DIR}/rev_A
	# shellcheck disable=SC2016
	printf "${b}" | \
		${ove_cmd2pathname["awk"]:?} '{print $1,$4}' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?}  > ${OVE_OWEL_TMP_DIR}/rev_B

	while true; do
		# repos only in A
		for r in $(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 ${OVE_OWEL_TMP_DIR}/repos_A ${OVE_OWEL_TMP_DIR}/repos_B); do
			${ove_cmd2pathname["grep"]:?} "^${r} " ${OVE_OWEL_TMP_DIR}/rev_A | ${ove_cmd2pathname["sed"]:?} -e 's/^/a /g'
		done

		# repos only in B
		for r in $(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -1 -3 ${OVE_OWEL_TMP_DIR}/repos_A ${OVE_OWEL_TMP_DIR}/repos_B); do
			${ove_cmd2pathname["grep"]:?} "^${r} " ${OVE_OWEL_TMP_DIR}/rev_B | ${ove_cmd2pathname["sed"]:?} -e 's/^/b /g'
		done

		# repos common for A and B
		for r in $(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -1 -2 ${OVE_OWEL_TMP_DIR}/repos_A ${OVE_OWEL_TMP_DIR}/repos_B); do
			# shellcheck disable=SC2016
			sha_1=$(${ove_cmd2pathname["grep"]:?} "^${r} " ${OVE_OWEL_TMP_DIR}/rev_A | \
				${ove_cmd2pathname["awk"]:?} '{print $2}')
			# shellcheck disable=SC2016
			sha_2=$(${ove_cmd2pathname["grep"]:?} "^${r} " ${OVE_OWEL_TMP_DIR}/rev_B | \
				${ove_cmd2pathname["awk"]:?} '{print $2}')
			if [ "${sha_1}" = "${sha_2}" ]; then
				continue
			fi
			echo c ${r} ${sha_1} ${sha_2}
		done

		break
	done | ${ove_cmd2pathname["column"]:?} -t

	# cleanup
	${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/repos_A \
		${OVE_OWEL_TMP_DIR}/repos_B \
		${OVE_OWEL_TMP_DIR}/rev_A \
		${OVE_OWEL_TMP_DIR}/rev_B
}

# helper function for diff/log/shortlog-owel functions
function ove_extract_only_a {
	local line=${*}
	local repo
	local sha_1

	# shellcheck disable=SC2016
	repo=$(${ove_cmd2pathname["awk"]:?} '{print $2}' <<<"${line}")
	# shellcheck disable=SC2016
	sha_1=$(${ove_cmd2pathname["awk"]:?} '{print $3}' <<<"${line}")
	if ove_dir_is_repo "${OVE_BASE_DIR}/${repo}"; then
		only_a+="  ${repo}|$(ove_repo_cmd ${OVE_BASE_DIR}/${repo} log -1 --oneline --pretty="  %C(auto)%h|%s" ${sha_1})\n"
	else
		only_a+="${line:1}\n"
	fi
}

# helper function for diff/log/shortlog-owel functions
function ove_extract_only_b {
	local line=${*}
	local repo
	local sha_1

	# shellcheck disable=SC2016
	repo=$(${ove_cmd2pathname["awk"]:?} '{print $2}' <<<"${line}")
	# shellcheck disable=SC2016
	sha_1=$(${ove_cmd2pathname["awk"]:?} '{print $3}' <<<"${line}")
	if ove_dir_is_repo "${OVE_BASE_DIR}/${repo}"; then
		only_b+="  ${repo}|$(ove_repo_cmd ${OVE_BASE_DIR}/${repo} log -1 --oneline --pretty="  %C(auto)%h|%s" ${sha_1})\n"
	else
		only_b+="${line:1}\n"
	fi
}

# helper function for diff/log/shortlog-owel functions
function ove_print_only_a_and_b {
	if [ "${only_a}" != "" ]; then
		echo
		ove_echo_yellow_noprefix "only in '$1':"
		printf "${only_a}" | ${ove_cmd2pathname["column"]:?} -t -s'|'
	fi

	if [ "${only_b}" != "" ]; then
		echo
		ove_echo_yellow_noprefix "only in '$2':"
		printf "${only_b}" | ${ove_cmd2pathname["column"]:?} -t -s'|'
	fi
}

# $1: repo
# $2: rev
function ove_validate_rev {
	local repo="$1"
	local revision="$2"

	if [ ! -d "${OVE_BASE_DIR}/${repo}" ]; then
		echo
		ove_echo_yellow_noprefix "${repo}: not yet fetched" 1>&2
		return 1
	fi

	if ! ove_repo_cmd "${OVE_BASE_DIR}/${repo}" cat-file -e "${revision}" &> /dev/null; then
		ove_echo_error_noprefix "${repo}: '${revision}' is not a valid revision"
		return 1
	fi
}

# helper function for diff/log/shortlog-owel functions
function ove_extract_repo_and_sha {
	local line=${*}

	# shellcheck disable=SC2016
	repo=$(${ove_cmd2pathname["awk"]:?} '{print $2}' <<<"${line}")
	# shellcheck disable=SC2016
	sha_1=$(${ove_cmd2pathname["awk"]:?} '{print $3}' <<<"${line}")
	if ! ove_validate_rev ${repo} ${sha_1}; then
		return 1
	fi
	# shellcheck disable=SC2016
	sha_2=$(${ove_cmd2pathname["awk"]:?} '{print $4}' <<<"${line}")
	if ! ove_validate_rev ${repo} ${sha_2}; then
		return 1
	fi
}

# diff-owel:<rev> <rev>:diff two OWEL revisions:CORE
function ove-diff-owel {
	ove_entry || return

	local cmd
	local diff
	local line
	local only_a
	local only_b
	local repo
	local sha_1
	local sha_2

	if ! ove_revtab_sanity_check "$@"; then
		ove_command_usage
		return 1
	fi

	cmd="ove_repo_cmd ${OVE_OWEL_DIR} diff --color=always $1 $2"
	diff=$(eval ${cmd})
	cmd="${ove_cmd2pathname["git"]:?} -C ${OVE_OWEL_DIR} diff --color=always $1 $2"
	if [ "${diff}" != "" ]; then
		if [ ${OVE_LESS_MORE_OPTIONS} -eq 1 ]; then
			echo -e "${diff}" | ${OVE_PAGER} -Ps"${OVE_OWEL_NAME}\:${cmd//./\\.}"
		else
			echo -e "${diff}" | ${OVE_PAGER}
		fi
	fi

	while IFS= read -r line; do
		if [ "${line}" = "" ]; then
			break
		elif [ ${line:0:1} = "a" ]; then
			ove_extract_only_a ${line}
		elif [ ${line:0:1} = "b" ]; then
			ove_extract_only_b ${line}
		elif [ ${line:0:1} = "c" ]; then
			if ! ove_extract_repo_and_sha ${line}; then
				continue
			fi
			cmd="ove_repo_cmd ${OVE_BASE_DIR}/${repo} diff --color=always ${sha_1} ${sha_2}"
			diff=$(eval ${cmd})
			cmd="${ove_cmd2pathname["git"]:?} -C ${OVE_BASE_DIR}/${repo} diff --color=always ${sha_1} ${sha_2}"
			if [ "${diff}" != "" ]; then
				if [ ${OVE_LESS_MORE_OPTIONS} -eq 1 ]; then
					echo -e "${diff}" | ${OVE_PAGER} -Ps"${repo}\:${cmd//./\\.}"
				else
					echo -e "${diff}" | ${OVE_PAGER}
				fi
			fi
		fi
	done <<<"$(ove-revtab-diff "$1" "$2")"

	ove_print_only_a_and_b $1 $2
}

# log-owel:<rev> <rev>:list commits between two OWEL revisions:CORE
function ove-log-owel {
	ove_entry || return

	local diff
	local line
	local only_a
	local only_b
	local repo
	local sha_1
	local sha_2

	if ! ove_revtab_sanity_check "$@"; then
		ove_command_usage
		return 1
	fi

	diff=$(ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager log" --oneline --pretty="  %C(auto)%h %s" "$1".."$2")
	if [ "${diff}" != "" ]; then
		ove_echo_yellow_noprefix "${OVE_OWEL_NAME}:"
		echo -e "${diff}"
	fi

	while IFS= read -r line; do
		if [ "${line}" = "" ]; then
			break
		elif [ ${line:0:1} = "a" ]; then
			ove_extract_only_a ${line}
		elif [ ${line:0:1} = "b" ]; then
			ove_extract_only_b ${line}
		elif [ ${line:0:1} = "c" ]; then
			if ! ove_extract_repo_and_sha ${line}; then
				continue
			fi
			diff=$(ove_repo_cmd ${OVE_BASE_DIR}/${repo} "--no-pager log" --oneline --pretty="  %C(auto)%h %s" ${sha_1}..${sha_2})
			if [ "${diff}" != "" ]; then
				echo
				ove_echo_yellow_noprefix "${repo}:"
				echo -e "${diff}"
			fi
		fi
	done <<<"$(ove-revtab-diff "$1" "$2")"

	ove_print_only_a_and_b $1 $2
}

# shortlog-owel:<rev> <rev>:shortlog two OWEL revisions:CORE
function ove-shortlog-owel {
	ove_entry || return

	local diff
	local line
	local only_a
	local only_b
	local repo
	local sha_1
	local sha_2

	if ! ove_revtab_sanity_check "$@"; then
		ove_command_usage
		return 1
	fi

	diff=$(ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager shortlog" --email --oneline "$1".."$2")
	if [ "${diff}" != "" ]; then
		ove_echo_yellow_noprefix ${OVE_OWEL_NAME}:
		echo -e "${diff}"
		echo
	fi

	while IFS= read -r line; do
		if [ "${line}" = "" ]; then
			break
		elif [ ${line:0:1} = "a" ]; then
			ove_extract_only_a ${line}
		elif [ ${line:0:1} = "b" ]; then
			ove_extract_only_b ${line}
		elif [ ${line:0:1} = "c" ]; then
			if ! ove_extract_repo_and_sha ${line}; then
				continue
			fi
			diff=$(ove_repo_cmd ${OVE_BASE_DIR}/${repo} "--no-pager shortlog" --email --oneline ${sha_1}..${sha_2} | ${ove_cmd2pathname["sed"]:?} -e 's/^/  /g')
			if [ "${diff}" != "" ]; then
				ove_echo_yellow_noprefix "${repo}:"
				echo -e "${diff}"
				echo
			fi
		fi
	done <<<"$(ove-revtab-diff "$1" "$2")"

	ove_print_only_a_and_b $1 $2
}

# help function that will print OVE workspace info
#
# $1 = path to OVE workspace directory
function ove_locate_print {
	local num_projs
	local num_repos
	local ove_dir
	local url

	ove_dir="$1/.owel"

	if [ ! -d ${ove_dir} ]; then
		return
	fi

	# shellcheck disable=SC2016
	num_repos=$(${ove_cmd2pathname["awk"]:?} '{print $1}' ${ove_dir}/revtab | \
		${ove_cmd2pathname["sed"]:?} -e 's/#.*$//' -e '/^$/d' | \
		${ove_cmd2pathname["wc"]:?} -l)
	OVE_OWEL_DIR=${ove_dir} num_projs=$(ove_list_projects | \
		${ove_cmd2pathname["wc"]:?} -w)
	${ove_cmd2pathname["dirname"]:?} ${ove_dir}
	if url=$(ove_repo_cmd "${ove_dir}" "config" --get remote.origin.url); then
		echo "  url: $url"
	fi
	# shellcheck disable=SC2016
	echo "  repos [${num_repos}]: $(${ove_cmd2pathname["awk"]:?} '{print $1}' ${ove_dir}/revtab | \
		${ove_cmd2pathname["sed"]:?} -e 's/#.*$//' -e '/^$/d' | \
		${ove_cmd2pathname["tr"]:?} '\n' ' ')"
	OVE_OWEL_DIR=${ove_dir} echo "  projs [${num_projs}]: $(ove_list_projects)"
	echo
}

function ove_resolve_url {
	local n
	local url

	if [ ! -d $OVE_GLOBAL_STATE_DIR/hub ]; then
		return 1
	fi

	url="$1"
	mapfile -t urls < <(ove-list-hub | ${ove_cmd2pathname["grep"]:?} "/$url$")
	n="${#urls[@]}"
	if [ "$n" -eq 0 ]; then
		return 1
	elif [ "$n" -eq 1 ]; then
		url="${urls[*]}"
	else
		printf "%s\n" "${urls[@]}" | ${ove_cmd2pathname["cat"]:?} -n 1>&2
		read -r -p "nbr: "
		if [[ ! "${REPLY}" =~ ^[0-9]+$ ]]; then
			if [ "${REPLY}" != "" ]; then
				ove_echo_error_noprefix "error: just numbers" 1>&2
			fi
			return 1
		elif [ "${REPLY}" -gt ${#urls[@]} ] || [ "${REPLY}" -eq 0 ]; then
			ove_echo_error_noprefix "0 < x <= ${#urls[@]}"
			return 1
		fi
		url=$(printf "%s\n" "${urls[@]}" | ${ove_cmd2pathname["head"]:?} -$REPLY | \
			${ove_cmd2pathname["tail"]:?} -1)
	fi

	if [ "$url" = "" ]; then
		return 1
	fi

	echo "$url"
}

# setup:[dir url [rev]]:setup OVE workspace:CORE
function ove-setup {
	local a
	local dir
	local n
	local url

	if [ $# -eq 1 ] || [ $# -gt 3 ]; then
		ove_command_usage
		return 1
	fi

	# dir
	if [ $# -eq 2 ] || [ $# -eq 3 ]; then
		dir="$1"
	else
		read -r -p "dir: "
		if [ "${REPLY}" = "" ]; then
			return 1
		fi
		dir="${REPLY}"
	fi

	if [ -e "$dir" ]; then
		ove_echo_error_noprefix "'$dir' exists"
		return 1
	fi

	# url
	if [ $# -eq 2 ] || [ $# -eq 3 ]; then
		url="$2"
		if [[ "$url" != *"/"* ]]; then
			if ! url=$(ove_resolve_url "$url"); then
				return 1
			fi
		fi
	else
		mapfile -t hub < <(ove-list-hub)
		if [ "${#hub[@]}" -eq 0 ]; then
			read -r -p "url: "
			if [ "${REPLY}" = "" ]; then
				return 1
			fi
			url="${REPLY}"
		else
			for a in "${hub[@]}"; do
				echo "${a##*/} ; $a"
			done | ${ove_cmd2pathname["column"]:?} -t -s';' | ${ove_cmd2pathname["cat"]:?} -n
			read -r -p "nbr: "
			if [[ ! "${REPLY}" =~ ^[0-9]+$ ]]; then
				if [ "${REPLY}" != "" ]; then
					ove_echo_error_noprefix "just numbers"
				fi
				return 1
			elif [ "${REPLY}" -gt ${#hub[@]} ] || [ "${REPLY}" -eq 0 ]; then
				ove_echo_error_noprefix "0 < x <= ${#hub[@]}"
				return 1
			fi
			url="${hub[$((REPLY - 1))]}"
		fi
	fi

	# rev
	if [ $# -eq 3 ]; then
		rev="$3"
	elif [ $# -eq 0 ]; then
		read -r -p "rev: "
		if [ "${REPLY}" != "" ]; then
			rev="${REPLY}"
		fi
	fi

	if ! eval "${OVE_DIR}"/setup "$dir" "$url" "$rev"; then
		return 1
	fi
}

# oneliner:[dir]:print or execute ${OVE_OWEL_DIR}/SETUP:CORE
function ove-oneliner {
	ove_entry || return

	local p
	local o
	local u

	if [ ! -s "${OVE_OWEL_DIR}/SETUP" ]; then
		if ! o="$(ove_repo_cmd "${OVE_OWEL_DIR}" "remote" | ${ove_cmd2pathname["head"]:?} -1)"; then
			return 0
		elif [ "$o" = "" ]; then
			return 0
		elif ! u=$(ove_repo_cmd "${OVE_OWEL_DIR}" "remote" "get-url" "$o"); then
			return 0
		elif [ "$u" = "" ]; then
			return 0
		fi
		echo "curl -sSL https://raw.githubusercontent.com/Ericsson/ove/master/setup | bash -s ${OVE_OWEL_NAME} ${u}"
		return 0
	elif [ ! -x "${OVE_OWEL_DIR}/SETUP" ]; then
		${ove_cmd2pathname["cat"]:?} "${OVE_OWEL_DIR}/SETUP"
		return 0
	fi

	if [ $# -eq 1 ]; then
		if [ ${EUID} -eq 0 ]; then
			p="#"
		else
			p="$"
		fi

		if ! echo "$p mkdir -p $1"; then
			return 1
		elif ! ${ove_cmd2pathname["mkdir"]:?} -p "$1"; then
			return 1
		elif ! echo "$p cd $1"; then
			return 1
		elif ! cd "$1"; then
			return 1
		fi
	fi

	if ! ${ove_cmd2pathname["bash"]:?} "${OVE_OWEL_DIR}/SETUP"; then
		return 1
	fi

	return 0
}

function ove_refresh_helper {
	local cmd
	local ret

	cmd="$1"
	ret=0
	if [[ ${cmd} =~ ^[Pp]$ ]]; then
		ove-pull
	elif [[ ${cmd} =~ ^[a]$ ]]; then
		ove-ahead
	elif [[ ${cmd} =~ ^[A]$ ]]; then
		ove-show-ahead
	elif [[ ${cmd} =~ ^[b]$ ]]; then
		ove-behind
	elif [[ ${cmd} =~ ^[B]$ ]]; then
		ove-show-behind
	elif [[ ${cmd} =~ ^[Cc]$ ]]; then
		ove-checkout
	elif [[ ${cmd} =~ ^[Dd]$ ]]; then
		ove-diff
	elif [[ ${cmd} =~ ^[f]$ ]]; then
		ove-fetch
	elif [[ ${cmd} =~ ^[F]$ ]]; then
		ove-fetch-fetched
	elif [[ ${cmd} =~ ^[Xx]$ ]]; then
		if ove-pull; then
			ret=1
		fi
	elif [[ ${cmd} =~ ^[Ll]$ ]]; then
		ove-log
	elif [[ ${cmd} =~ ^[s]$ ]]; then
		ove-status
	elif [[ ${cmd} =~ ^[S]$ ]]; then
		ove-show-news
	elif [[ ${cmd} =~ ^[Qq]$ ]]; then
		return 2
	elif [[ ${cmd} =~ ^[Nn]$ ]]; then
		ret=1
	elif [[ ${cmd} =~ ^[h]$ ]]; then
		echo 'a - ahead'
		echo 'A - show-ahead'
		echo 'b - behind'
		echo 'B - show-behind'
		echo 'c - checkout'
		echo 'd - diff'
		echo 'f - fetch'
		echo 'F - fetch-fetched'
		echo 'h - this help'
		echo 'l - log'
		echo 'n - next'
		echo 'p - pull'
		echo 'q - quit'
		echo 's - status'
		echo 'S - show-news'
		echo 'x - pull and next'
	fi
	echo

	return ${ret}
}

# refresh:[pattern...]:refresh OVE workspaces on this host:UTIL
function ove-refresh {
	ove_entry || return

	local i
	local p
	local proj_base
	local proj_list
	local projs
	local str

	mapfile -t projs < <(ove_list_workspaces_full)
	if [ $# -eq 0 ]; then
		proj_list="$(${ove_cmd2pathname["seq"]:?} 0 $((${#projs[@]} - 1)))"
	else
		i=0
		while ((i < ${#projs[@]})); do
			proj_base=${projs[i]##*/}
			for p in "$@"; do
				if [[ "${proj_base,,}" =~ ${p,,} ]]; then
					proj_list+="$i "
				fi
			done
			(( i+=1 ))
		done
	fi

	for i in ${proj_list}; do
		echo "# $(ove_echo_green_noprefix ${projs[i]##*/})"
		echo "$ cd ${projs[i]}"
		if ! cd "${projs[i]}"; then
			continue
		fi
		ove_init
		if [ "${OVE_REFRESH_STEPS}" = "interactive" ]; then
			echo "$ ove fetch-fetched"
			ove-fetch-fetched
			if ove-news > /dev/null; then
				ove-news
				while true; do
					read -p "$(ove_echo_green_noprefix ${projs[i]##*/}) [a,A,b,B,c,d,f,F,h,l,n,p,q,s,S,x]? " -r -n1
					echo
					ove_refresh_helper $REPLY
					ret=$?
					if [ $ret -eq 1 ]; then
						break
					elif [ $ret -eq 2 ]; then
						return
					fi
				done
			fi
		else
			for cmd in ${OVE_REFRESH_STEPS}; do
				ove_refresh_helper $cmd
				ret=$?
				if [ $ret -eq 1 ]; then
					break
				elif [ $ret -eq 2 ]; then
					return
				fi
			done
		fi
	done
}

function ove_locate_owels {
	local a
	local b
	local diff
	local invalidate_cache
	local o
	local owels

	if [ -e "${OVE_GLOBAL_STATE_DIR}/owel.cache" ]; then
		a=$(${ove_cmd2pathname["stat"]:?} --format '%Y' "${OVE_GLOBAL_STATE_DIR}/owel.cache")
		b=$(${ove_cmd2pathname["date"]:?} +%s)
		if [ $((b-a)) -lt ${OVE_LOCATE_LIFESPAN_TIME_IN_SEC} ]; then
			for o in $(${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/owel.cache"); do
				if ! [ -d ${o} ]; then
					invalidate_cache=true
				fi
			done

			if ! [ "${invalidate_cache}" = true ]; then
				${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/owel.cache"
				return
			fi
		fi
	fi

	if command -v locate > /dev/null; then
		owels=$(${ove_cmd2pathname["locate"]:?} -e -r '\.owel$')
	else
		ove_echo_warning_noprefix "command 'locate' is missing, this could take some time"
		owels=$(${ove_cmd2pathname["find"]:?} ${OVE_LOCATE_SEARCH_DIR} -xdev -type l -name .owel 2> /dev/null)
	fi

	if [ "${owels}" = "" ]; then
		return 1
	fi

	for o in ${owels}; do
		if ! ove_is_base_dir "$o"; then
			continue
		fi
		owels=${owels/${o}/}
	done

	owels=${owels//\/.owel/}

	printf "%s\n" ${owels} | \
		${ove_cmd2pathname["tee"]:?} "${OVE_GLOBAL_STATE_DIR}/owel.cache"
}

function ove_list_workspaces_full {
	local owel
	local owels

	owels=$(ove_locate_owels)

	if [ "${owels}" = "" ]; then
		ove_echo_error_noprefix "no OVE workspace(s) found"
		return 1
	fi

	for owel in ${owels}; do
		if [ -O ${owel}/ove ]; then
			echo ${owel}
		fi
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

function ove_list_workspaces_base {
	local owel

	for owel in $(ove_list_workspaces_full); do
		echo ${owel##*/}
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

# locate: :print OVE workspaces owned by you on this host:CORE
function ove-locate {
	ove_entry || return

	local owel
	local owels

	owels=$(ove_list_workspaces_full)
	for owel in ${owels}; do
		ove_locate_print ${owel}
	done | ${ove_cmd2pathname["head"]:?} -n -1
}

# locate-all: :print all OVE workspaces on this host:CORE
function ove-locate-all {
	ove_entry || return

	local owel
	local owels

	owels=$(ove_locate_owels)
	if [ "${owels}" = "" ]; then
		ove_echo_error_noprefix "no OVE workspace(s) found"
		return 1
	fi

	for owel in ${owels}; do
		ove_locate_print ${owel}
	done | ${ove_cmd2pathname["head"]:?} -n -1
}

# helper function for ove_set_workspace
function ove_set_workspaces_helper {
	local i=0

	if [ -z ${projs+x} ]; then
		return 1
	elif [ ${#projs[@]} -eq 0 ]; then
		return 1
	fi
	while ((i < ${#projs[@]})); do
		printf "%d # %s # %s\n" $((i + 1)) $(ove_echo_green_noprefix ${projs[i]##*/}) ${projs[i]}
		(( i+=1 ))
	done | ${ove_cmd2pathname["column"]:?} -t -s#
}

# move to a specific OVE workspace
# $1: PATTERN
function ove_set_workspace {
	local i=0
	local p
	local projs

	mapfile -t projs < <(ove_list_workspaces_full)
	if [ ${#projs[@]} -eq 0 ]; then
		return 1
	elif [ $# -eq 0 ]; then
		ove_set_workspaces_helper
		echo
		read -r -p "workspace? "
		if [[ ! "${REPLY}" =~ ^[0-9]+$ ]]; then
			if [ "${REPLY}" != "" ]; then
				echo "error: just numbers" 1>&2
			fi
			return 1
		fi

		if [ ${REPLY} -gt ${#projs[@]} ] || [ ${REPLY} -eq 0 ]; then
			echo "error: out of bounds" 1>&2
			return 1
		fi

		eval $(printf "cd %s; . ove > /dev/null\n" ${projs[$((REPLY - 1))]})
	elif [ $# -eq 1 ]; then
		while ((i < ${#projs[@]})); do
			p=${projs[i]##*/}
			if [[ "${p,,}" =~ ${1,,} ]]; then
				eval $(printf "cd %s; . ove > /dev/null\n" ${projs[i]})
				return
			fi
			(( i+=1 ))
		done

		echo "error: workspace '$1' not found" 1>&2
		echo "Your OVE workspace(s) on this host:"
		ove_set_workspaces_helper
		return 1
	fi
}

# update-revtab:git rev:update 'revtab' with a another (existing) 'rev' for the repository named 'git':CORE
function ove-update-revtab {
	ove_entry || return

	local i
	local repo
	local revision

	if [ ${#} -ne 2 ]; then
		ove_command_usage
		return 1
	fi

	ove_revtab_sanity || return

	# validate repo
	repo=$(ove_validate_repo_list ${1})
	if [ "${repo}" = "" ]; then
		ove_echo_error_noprefix "repo '${1}' is not valid repo name"
		ove_command_usage
		return 1
	fi

	# validate revision
	revision="$2"
	if ! ove_validate_rev ${repo} ${revision}; then
		ove_command_usage
		return 1
	fi

	# update revtab
	i=${ove_revtab_name2index[${repo}]}
	${ove_cmd2pathname["sed"]:?} -i "s|^\(${repo} .*\)${ove_revtab_rev[${i}]}|\1${revision}|g" "${OVE_OWEL_DIR}/revtab"

	# reinit
	ove_reinit
}

# branch:[git...]|[git... name]:list branch(es) or create-and-checkout 'name' branch for 'git...' and update 'revtab' accordingly:CORE
function ove-branch {
	ove_entry || return
	ove_revtab_sanity || return

	local a
	local args
	local branch_name
	local branch_start_point
	local cmd
	local i
	local r
	local repos
	local ret=0

	if [ $# -lt 2 ]; then
		# shellcheck disable=SC2016
		cmd='ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} "--no-pager branch" | ${ove_cmd2pathname["sed"]:?} "s|^|$(printf "%-${OVE_REPO_LIST_WIDTH}s" ${repo_basename})|g"'
		if [ $# -eq 0 ]; then
			ove_revtab_forall "${cmd}"
		else
			ove_revtab_forsome "${cmd}" "$@"
		fi

		return 0
	fi

	read -r -a a <<<"$*"
	# all but last arg
	args=${a[*]:0:${#a[*]}-1}
	branch_name=${a[*]: -1}
	repos=$(ove_validate_repo_list ${args})
	if [ "${repos}" = "" ]; then
		echo "error: invalid repo name: '${args}'" 1>&2
		return 1
	fi

	for r in ${repos}; do
		if ! ove_dir_is_repo "${OVE_BASE_DIR}/${r}"; then
			echo "error: repo '${r}' is not yet fetched" 1>&2
			continue
		fi

		while true; do
			read -r -p "${r}: starting point for branch '${branch_name}'? (leave empty to create branch from current HEAD): "
			if [ "${REPLY}" = "" ]; then
				break
			elif ! ove_repo_cmd "${OVE_BASE_DIR}/${r}" cat-file -e "${REPLY}" &> /dev/null; then
				ove_echo_error_noprefix "'${REPLY}' is not a valid revision for ${r}, try again"
				continue
			fi
			branch_start_point=${REPLY}
			break
		done

		# checkout branch
		ove_repo_cmd "${OVE_BASE_DIR}/${r}" checkout -b ${branch_name} ${branch_start_point} |& ${ove_cmd2pathname["sed"]:?} "s|^|${r}: |g"
		if [ ${PIPESTATUS[0]} -ne 0 ]; then
			((ret++))
			continue
		fi

		if [ ! -e "${OVE_OWEL_DIR}/revtab" ]; then
			continue
		elif [ "${OVE_OWEL_NAME}" = "${r}" ]; then
			continue
		fi

		ove-update-revtab ${r} ${branch_name}
	done

	return ${ret}
}

# remote:[git...]:git remote -v for all/specified git repositories:CORE
function ove-remote {
	ove_entry || return

	local cmd
	declare -a repos

	# shellcheck disable=SC2016
	cmd='ove_echo_yellow_noprefix ${repo_basename} && ove_repo_cmd ${repo} "--no-pager remote" -v'

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
		if [ "${#repos[@]}" -eq 0 ]; then
			return
		fi
		ove_revtab_forsome "${cmd}" "${repos[@]}"
	fi
}

# remote-set-url:url [git...]:change the URL of 'origin' remote for all/specified repositories:CORE
function ove-remote-set-url {
	ove_entry || return

	declare -a repos
	local cmd
	local url

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi
	url=$1
	shift

	# shellcheck disable=SC2016
	cmd='ove_echo_yellow_noprefix ${repo_basename} && ove_repo_cmd ${repo} "--no-pager remote" set-url origin ${url}/${repo_basename} && ove_repo_cmd ${repo} "--no-pager remote" -v'

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
		if [ "${#repos[@]}" -eq 0 ]; then
			return
		fi
		ove_revtab_forsome "${cmd}" "$@"
	fi
}

# remote-check: :sanity check that all remotes are online:CORE
function ove-remote-check {
	ove_entry || return

	local i
	local url

	i=0
	while ((i < ove_revtab_num_repositories)); do
		url="${ove_revtab_fetch_url[${i}]}"
		if [ "${url}" = "noremote" ]; then
			(( i+=1 ))
			continue
		fi

		if ! ${ove_cmd2pathname["git"]:?} ls-remote ${url} HEAD > /dev/null; then
			return 1
		fi

		(( i+=1 ))
	done
}

function ove_repo_is_dirty {
	if test -z "$(ove_repo_cmd ${1} "${OVE_GIT_OPTIONS} --no-pager status" --porcelain -uno)"; then
		return 1
	else
		return 0
	fi
}

# $1: repo
# $2: 1 = index or 2 = worktree
function ove_repo_is_dirty_helper {
	local s

	s="$(ove_repo_cmd ${1} "${OVE_GIT_OPTIONS} --no-pager status" --porcelain -uno)"
	if [ "${s}" = "" ]; then
		return 1
	fi
	s=$(${ove_cmd2pathname["cut"]:?} -b${2} <<<"$s")
	s=${s//$'\n'/}
	s=${s//[[:space:]]/}
	if [ "${s}" = "" ]; then
		return 1
	else
		return 0
	fi
}

function ove_repo_is_dirty_index {
	ove_repo_is_dirty_helper "${1}" 1
	return $?
}

function ove_repo_is_dirty_worktree {
	ove_repo_is_dirty_helper "${1}" 2
	return $?
}

function ove_list_dirty_repos {
	local repo

	# shellcheck disable=SC2016
	for repo in $(ove_revtab_forall_parallel 'ove_repo_is_dirty ${repo} && echo ${PWD}'); do
		ove_repo2shortpath ${repo}
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

function ove_list_dirty_repos_index {
	local repo

	# shellcheck disable=SC2016
	for repo in $(ove_revtab_forall_parallel 'ove_repo_is_dirty_index ${repo} && echo ${PWD}'); do
		ove_repo2shortpath ${repo}
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

function ove_list_dirty_repos_worktree {
	local repo

	# shellcheck disable=SC2016
	for repo in $(ove_revtab_forall_parallel 'ove_repo_is_dirty_worktree ${repo} && echo ${PWD}'); do
		ove_repo2shortpath ${repo}
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

function ove_stashed_repos {
	# shellcheck disable=SC2016
	ove_revtab_forall_parallel 'ove_repo_cmd ${repo} "--no-pager stash" list | ${ove_cmd2pathname["grep"]:?} -q "stashed by OVE" && echo ${repo}'
}

# $1: drop or pop
# $2: [pattern]
function ove_stash_forsome {
	local repo
	local s
	local t

	for repo in $(ove_stashed_repos); do
		s=$(ove_repo_cmd ${repo} stash list | \
			${ove_cmd2pathname["grep"]:?} "stashed by OVE")

		if [ $# -eq 2 ] && [[ ${s} != *"$2"* ]]; then
			continue
		fi

		if [ $# -eq 1 ]; then
			t=$(echo "$s" | \
				${ove_cmd2pathname["head"]:?} -1 | \
				${ove_cmd2pathname["cut"]:?} -d: -f1)
			ove_repo_cmd ${repo} stash $1 -q ${t}
		else
			while true; do
				s=$(ove_repo_cmd ${repo} stash list | \
					${ove_cmd2pathname["grep"]:?} "stashed by OVE" | \
					${ove_cmd2pathname["grep"]:?} ${2} | \
					${ove_cmd2pathname["head"]:?} -1 | \
					${ove_cmd2pathname["cut"]:?} -d: -f1)
				if [ "${s}" = "" ]; then
					break
				elif ! ove_repo_cmd ${repo} stash $1 -q ${s}; then
					ove_echo_error_noprefix "git -C ${repo} stash $1 -q ${s} failed"
					return 1
				fi
			done
		fi
	done
}

function ove_stash_pop {
	ove_stash_forsome pop $1
}

function ove_stash_drop {
	ove_stash_forsome drop $1
}

# $*: [message]
function ove_stash_push {
	local cmd
	declare -a dirty_repos
	local now

	mapfile -t dirty_repos < <(ove_list_dirty_repos)
	if [ "${#dirty_repos[*]}" -eq 0 ]; then
		return
	fi

	now=$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S')
	cmd="ove_repo_cmd \${repo} stash save -q stashed by OVE@${now}"
	if [ $# -eq 0 ]; then
		cmd+=" ${dirty_repos[*]}"
	else
		cmd+=" ${*}"
	fi

	ove_revtab_forsome "${cmd}" "${dirty_repos[@]}"
}

# $1: show or list
# $2: [pattern]
function ove_stash_inspect {
	local cmd
	local repo
	local s
	local t
	local u

	for repo in $(ove_stashed_repos); do
		cmd="ove_repo_cmd ${repo} stash"
		if [ "$1" = "show" ]; then
			s=$(ove_repo_cmd ${repo} stash list | \
				${ove_cmd2pathname["grep"]:?} "stashed by OVE")

			if [ $# -eq 2 ] && [[ ${s} != *"$2"* ]]; then
				continue
			fi

			if [ $# -eq 1 ]; then
				t=$(echo "$s" | \
					${ove_cmd2pathname["head"]:?} -1 | \
					${ove_cmd2pathname["cut"]:?} -d: -f1)
			else
				t=$(echo "$s" | \
					${ove_cmd2pathname["grep"]:?} ${2} | \
					${ove_cmd2pathname["cut"]:?} -d: -f1)
			fi

			cmd+=" show -p"
			for u in ${t}; do
				ove_echo_yellow_noprefix "${repo/${OVE_BASE_DIR}\/}:${u}"
				eval ${cmd} ${u}
			done
		else
			ove_echo_yellow_noprefix "${repo/${OVE_BASE_DIR}\/}"
			cmd+=" list | ${ove_cmd2pathname["grep"]:?} 'stashed by OVE'"
			eval ${cmd}
		fi
	done
}

function ove_stash_show {
	ove_stash_inspect show $1
}

function ove_stash_list {
	ove_stash_inspect list $1
}

# stash:[list|show [pattern]|drop [pattern]|pop [pattern]|push [msg...]]:git stash [drop|pop|show|list|push] for all git repositories:CORE
function ove-stash {
	ove_entry || return

	if [ "$1" = "pop" ] ||
		[ "$1" = "list" ] ||
		[ "$1" = "show" ] ||
		[ "$1" = "drop" ]; then
		ove_stash_$1 $2
	elif [ "$1" = "save" ] || [ "$1" = "push" ] || [ $# -eq 0 ]; then
		ove_stash_push "${@:2}"
	else
		ove_command_usage
		return 1
	fi
}

# diff:[git...]:git diff for all/specified git repositories:CORE
function ove-diff {
	ove_entry || return

	local cmd
	declare -a repos

	if [ $# -eq 0 ]; then
		mapfile -t repos < <(ove_list_dirty_repos_worktree)
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
	fi

	if [ "${repos[*]}" = "" ]; then
		return
	fi

	cmd="ove_repo_cmd \${repo} '--no-pager diff-files' --quiet || \
		(ove_echo_yellow_noprefix \${repo_basename} && \
		ALLOW_OVERRIDE=1 ove_repo_cmd \${repo} '--no-pager diff' ${OVE_DIFF_OPTIONS})"

	ove_revtab_forsome "${cmd}" "${repos[@]}" | ${OVE_PAGER}
}

# wdiff:[git...]:git diff (word diff) for all/specified git repositories:CORE
function ove-wdiff {
	ove_entry || return

	local OVE_DIFF_OPTIONS

	OVE_DIFF_OPTIONS="--color-words=."
	ove-diff "$@"
}

# wdiff-cached:[git...]:git diff --cached (word diff) for all/specified git repositories:CORE
function ove-wdiff-cached {
	ove_entry || return

	local OVE_DIFF_OPTIONS

	OVE_DIFF_OPTIONS="--color-words=."
	ove-diff-cached "$@"
}

# diff-cached:[git...]:git diff --cached for all/specified repositories:CORE
function ove-diff-cached {
	ove_entry || return

	local cmd
	declare -a repos

	cmd="ove_repo_cmd \${repo} '--no-pager diff-index' --quiet --cached HEAD -- || \
		(ove_echo_yellow_noprefix \${repo_basename} && \
		ALLOW_OVERRIDE=1 ove_repo_cmd \${repo} '--no-pager diff' --cached ${OVE_DIFF_OPTIONS})"

	if [ $# -eq 0 ]; then
		mapfile -t repos < <(ove_list_dirty_repos_index)
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
	fi

	if [ "${#repos[@]}" -eq 0 ]; then
		return
	fi

	ove_revtab_forsome "${cmd}" "${repos[@]}" | ${OVE_PAGER}
}

# reset:[git...]:git reset for all/specified repositories:CORE
function ove-reset {
	ove_entry || return

	local cmd

	# shellcheck disable=SC2016
	cmd='ove_repo_cmd ${repo} "--no-pager diff-index" --quiet --cached HEAD -- ||'
	# shellcheck disable=SC2016
	cmd+=' (ove_echo_yellow_noprefix ${repo_basename} && ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} reset)'

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		ove_revtab_forsome "${cmd}" "$@"
	fi
}

# reset-hard:[git...]:git reset --hard for all/specified repositories, USE WITH CARE:CORE
function ove-reset-hard {
	ove_entry || return

	local cmd

	# shellcheck disable=SC2016
	cmd='ove_repo_cmd ${repo} reset -q --hard'

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		ove_revtab_forsome "${cmd}" "$@"
	fi
}

# add:[git...]:git add for all/specified repositories:CORE
function ove-add {
	ove_entry || return

	local cmd
	declare -a repos

	# shellcheck disable=SC2016
	cmd='ove_repo_cmd ${repo} "--no-pager diff-files" --quiet ||'
	# shellcheck disable=SC2016
	cmd+=' (ove_echo_yellow_noprefix ${repo_basename} && ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} "--no-pager add")'

	if [ $# -eq 0 ]; then
		mapfile -t repos < <(ove_list_dirty_repos_worktree)
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
	fi

	if [ "${#repos[@]}" -eq 0 ]; then
		return
	fi

	ove_revtab_forsome "${cmd}" "${repos[@]}"
}

# commit:[git...]:git commit for all/specified git repositories:CORE
function ove-commit {
	ove_entry || return

	local cmd
	declare -a repos

	cmd="ove_repo_cmd \${repo} '--no-pager diff' --cached --quiet ||
		(ove_echo_yellow_noprefix \${repo_basename};
		true > ${OVE_OWEL_TMP_DIR}/commit-template;
		echo >> ${OVE_OWEL_TMP_DIR}/commit-template;
		echo \# git: \${repo} >> ${OVE_OWEL_TMP_DIR}/commit-template;
		echo \# >> ${OVE_OWEL_TMP_DIR}/commit-template;
		ove_repo_cmd \${repo} diff --cached -U0 | ${ove_cmd2pathname["sed"]:?} 's/^/# /g' >> ${OVE_OWEL_TMP_DIR}/commit-template;
		ove_repo_cmd \${repo} commit -t ${OVE_OWEL_TMP_DIR}/commit-template;
		${ove_cmd2pathname["rm"]:?} ${OVE_OWEL_TMP_DIR}/commit-template)"

	if [ $# -eq 0 ]; then
		mapfile -t repos < <(ove_list_dirty_repos_index)
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
	fi

	if [ "${#repos[@]}" -eq 0 ]; then
		return
	fi

	ove_revtab_forsome "${cmd}" "${repos[@]}"
}

# list-missing-projects:[project...|tag...]:list any missing project(s):CORE
function ove-list-missing-projects {
	ove_entry || return

	local d
	declare -A m
	local proj_list

	if [ $# -eq 0 ]; then
		proj_list="${OVE_PROJECT_LIST}"
	else
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi
	fi

	for d in $(ove_get_deps_recursive ${proj_list}); do
		if [[ ! -v ove_projects_name2index[${d}] ]]; then
			m[${d}]=
		fi
	done

	if [ ${#m[@]} -ne 0 ]; then
		printf "%s\n" "${!m[@]}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
	fi
}

# $* = proj(s)
function ove_get_deps_recursive {
	local dep
	local i
	local proj

	for proj in "$@"; do
		if [[ ! -v ove_projects_name2index[${proj}] ]]; then
			continue
		fi
		i=${ove_projects_name2index[${proj}]}
		for dep in ${ove_projects_deps[${i}]}; do
			echo -n "${dep} "
			ove_get_deps_recursive ${dep}
		done
	done
}

# $1 = proj
function ove_get_paths_recursive {
	local dep
	local i

	if [ $# -ne 1 ]; then
		return 1
	elif [[ ! -v ove_projects_name2index[${1}] ]]; then
		return
	fi
	i=${ove_projects_name2index[$1]}

	if [ "${ove_projects_deps[${i}]}" = "" ]; then
		echo -n "${ove_projects_path[${i}]} "
		return
	fi

	for dep in ${ove_projects_deps[${i}]}; do
		echo -n "${ove_projects_path[${i}]} "
		ove_get_paths_recursive ${dep}
	done
}

# proj2val:project...|tag... key:print project(s) value based on key:CORE
function ove-proj2val {
	ove_entry || return

	local err
	local k
	local p
	local proj_list
	local r

	if [ $# -lt 2 ]; then
		ove_command_usage
		return 1
	elif ! proj_list=$(ove_validate_project_list "${@:1:$#-1}"); then
		return 1
	fi

	k="${*: -1}"
	err=0
	for r in ${proj_list}; do
		local i
		local -n p="ove_${r}_${k}"
		local -n q="ove_projects_${k}"

		if [[ -v ${!p} ]]; then
			if [ "$p" != "" ]; then
				printf "%s\n" $p
			else
				err=$((err + 1))
			fi
		else
			if [[ ! -v q[*] ]]; then
				err=$((err + 1))
			else
				i=${ove_projects_name2index[$r]}
				if [ "${q[${i}]}" != "" ]; then
					printf "%s\n" ${q[${i}]}
				fi
			fi
		fi
	done

	return ${err}
}

function ove_revtab_validate {
	local a
	local foo
	local d
	local doublets

	if [ ! -e "${OVE_OWEL_DIR}/revtab" ]; then
		return
	fi

	declare -A r=()
	while read -r a foo; do
		# ignore comments and emtpy lines
		if [[ ${a} == \#* ]] || [[ ${a} == '' ]]; then
			continue
		fi
		if test "${r["${a}"]+isset}"; then
			ove_echo_error_noprefix "found repo doublet(s) in '${OVE_OWEL_DIR}/revtab':"
			# shellcheck disable=SC2016
			doublets="$(${ove_cmd2pathname["grep"]:?} -E -v '^$|^#' ${OVE_OWEL_DIR}/revtab | \
				${ove_cmd2pathname["awk"]:?} 'a[$1]++{print $1}' | \
				LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u)"
			for d in ${doublets}; do
				${ove_cmd2pathname["grep"]:?} --color=never -n "^${d} " ${OVE_OWEL_DIR}/revtab
			done
			return 1
		fi
		r["${a}"]=1
	done <"${OVE_OWEL_DIR}/revtab"
}

# $1: file
function ove_validate_tabs_and_space {
	local f

	f="$1"

	if ${ove_cmd2pathname["grep"]:?} -q -P '^\t+ ' ${f}; then
		ove_echo_error_noprefix "tab followed by space:"
		${ove_cmd2pathname["grep"]:?} -H -n -P '^\t+ ' ${f} | \
			${ove_cmd2pathname["sed"]:?} -n 'l'
		return 1
	elif ${ove_cmd2pathname["grep"]:?} -q -P '^ +\t+' ${f}; then
		ove_echo_error_noprefix "space followed by tab:"
		${ove_cmd2pathname["grep"]:?} -H -n -P '^ +\t+' ${f} | \
			${ove_cmd2pathname["sed"]:?} -n 'l'
		return 1
	fi
}

function ove_validate_self {
	local funcs

	if ${ove_cmd2pathname["grep"]:?} ^function ${OVE_SELF} | \
		${ove_cmd2pathname["grep"]:?} -q -v 'function ove'; then
		ove_echo_error_noprefix "functions need to start with 'ove-' or 'ove_'"
		${ove_cmd2pathname["grep"]:?} ^function ${OVE_SELF} | \
			${ove_cmd2pathname["grep"]:?} -v 'function ove'
		return 1
	fi

	funcs=$(${ove_cmd2pathname["grep"]:?} -B1 '^function ove-' ${OVE_SELF})

	# shellcheck disable=SC2016
	if [ "$(${ove_cmd2pathname["grep"]:?} '^$' -A1 <<< "${funcs}" | \
		${ove_cmd2pathname["awk"]:?} '{print $2}' | \
		${ove_cmd2pathname["xargs"]:?})" != "" ]; then
		ove_echo_error_noprefix "add help for the following function(s):"
		# shellcheck disable=SC2016
		${ove_cmd2pathname["grep"]:?} '^$' -A1 <<< "${funcs}" | \
			${ove_cmd2pathname["awk"]:?} '{print $2}' | \
			${ove_cmd2pathname["xargs"]:?}
		return 1
	fi

	ove_validate_tabs_and_space "${OVE_SELF}"
}

function ove_validate_projs {
	local d
	local doublets
	local i
	local name
	declare -a r

	if [ ! -e "${OVE_OWEL_DIR}/projs" ]; then
		return
	fi

	i=0
	while ((i < ove_number_of_projects)); do
		name="${ove_projects_name[${i}]}"
		if [ "${ove_projects_deps[${i}]}" != "" ]; then
			for d in ${ove_projects_deps[${i}]}; do
				if [ "${ove_projects_name[${i}]}" = "${d}" ]; then
					ove_echo_error_noprefix "circular dependency in '${OVE_OWEL_DIR}/projs' detected. Project '${d}' is dependent on '${d}'."
					return 1
				fi
				echo "${ove_projects_name[${i}]} ${d}"
			done
		fi

		if [[ -v ove_projects_tags[${name}] ]]; then
			ove_echo_error_noprefix "tag '${name}' is already used as a project name, try another tag!"
			${ove_cmd2pathname["grep"]:?} -C 3 -n -H -w -E "^${name}:|${name}" ${OVE_OWEL_DIR}/projs 1>&2
			return 1
		fi
		(( i+=1 ))
	done | ${ove_cmd2pathname["tsort"]:?} > /dev/null
	read -r -a r <<<"${PIPESTATUS[@]}"

	if [ ${r[0]} -ne 0 ]; then
		return 1
	elif [ ${r[1]} -ne 0 ]; then
		ove_echo_error_noprefix "circular dependency in '${OVE_OWEL_DIR}/projs', see output from 'tsort' above"
		return 1
	fi

	# shellcheck disable=SC2016
	doublets=$(${ove_cmd2pathname["grep"]:?} -o '^[a-zA-Z0-9_]\+' ${OVE_OWEL_DIR}/projs | \
		${ove_cmd2pathname["awk"]:?} 'a[$1]++{print $1}')

	if [ "${doublets}" != "" ]; then
		ove_echo_error_noprefix "found project doublet(s) in '${OVE_OWEL_DIR}/projs':"

		for d in ${doublets}; do
			${ove_cmd2pathname["grep"]:?} -n "^${d}:" ${OVE_OWEL_DIR}/projs
		done
		return 1
	fi
}

# $@: a list of packages
function ove_install_packages {
	local cmd
	local missing_packages
	local missing_packages_sorted

	if [ ${OVE_INSTALL_PKG:?} -eq 0 ]; then
		return
	fi
	missing_packages=$(ove_packages_not_installed "$@")

	# no missing packages?
	if [ "${missing_packages}" = "" ]; then
		return
	fi

	# sort the list
	missing_packages_sorted="$(printf "%s\n" ${missing_packages} | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u)"
	missing_packages_sorted=${missing_packages_sorted//$'\n'/ }

	if [ "${OVE_DRY_RUN}" -eq 1 ]; then
		ove_echo_yellow "would prompt to install this/these package(s):"
		printf "%s\n" ${missing_packages_sorted}
		return
	fi

	if [ "${OVE_OS_PACKAGE_MANAGER}" = "unknown" ]; then
		ove_echo_fatal_noprefix "package manager is not set"
		return 1
	fi

	if ! command -v ${OVE_OS_PACKAGE_MANAGER} > /dev/null; then
		ove_command_not_found "${OVE_OS_PACKAGE_MANAGER}"
		return 1
	fi

	cmd="${OVE_OS_PACKAGE_MANAGER} ${OVE_OS_PACKAGE_MANAGER_ARGS} ${missing_packages_sorted}"
	if [ ${EUID} != 0 ]; then
		if [ "${OVE_INSTALL_PKG_ELEVATE_METHOD:?}" = "sudo" ]; then
			cmd="${ove_cmd2pathname["sudo"]:?} ${cmd}"
		elif [ "${OVE_INSTALL_PKG_ELEVATE_METHOD:?}" = "su" ]; then
			cmd="${ove_cmd2pathname["su"]:?} -c \"${cmd}\""
		else
			ove_echo_fatal_noprefix "unknown elevate method '${OVE_INSTALL_PKG_ELEVATE_METHOD:?}'"
			return 1
		fi
	fi

	if [ ${OVE_INSTALL_PKG:?} -eq 1 ]; then
		if ! eval ${cmd}; then
			ove_echo_fatal_noprefix "'${cmd}' failed"
			return 1
		fi
		return 0
	elif [ ${OVE_INSTALL_PKG:?} -eq 2 ]; then
		echo "error: missing package(s): '${missing_packages_sorted}'. To fix this, run the following command:" 1>&2
		echo 1>&2
		echo -e "\t${cmd}" 1>&2
		echo 1>&2
		return 1
	fi
}

# $1: patch file
# $2: key
function ove_modify_patch {
	local f
	local key
	local n

	f="$1"
	key="$2"

	n=$(${ove_cmd2pathname["grep"]:?} -n "^+++ b/${key}" ${f})
	n=${n%%:*}
	((n++))
	${ove_cmd2pathname["sed"]:?} -i \
		-e "${n}s, -0, -99999,g" \
		-e "${n}s/ -[0-9]\+,0 +[0-9]\+,\([0-9]\+\) @@.*/ -99999,0 +1,\1 @@/g" \
		${f}
}

# $1: proj
# $2: work dir
function ove_export_create_proj_patch {
	local f
	local proj
	local wd

	wd="$2"

	# symlink to another project?
	if [ -h ${OVE_OWEL_DIR}/projects/$1 ]; then
		if ! proj="$(${ove_cmd2pathname["readlink"]} ${OVE_OWEL_DIR}/projects/$1)"; then
			return 1
		fi
		echo "$proj"
		if ! ${ove_cmd2pathname["mkdir"]:?} -p "${wd}"/projects/${proj}; then
			return 1
		elif ! (cd "${wd}"/projects || exit 1; ${ove_cmd2pathname["ln"]:?} -s ${proj} ${1}); then
			return 1
		elif ! (cd "${wd}" || exit 1; ${ove_cmd2pathname["git"]:?} add projects/${1}
			${ove_cmd2pathname["git"]:?} diff --cached >> "${wd}"/${1}.patch); then
			return 1
		fi
	else
		proj="$1"
	fi

	# project commands
	if ${ove_cmd2pathname["find"]:?} ${OVE_OWEL_DIR}/projects/${proj} -mindepth 1 -print -quit 2> /dev/null | ${ove_cmd2pathname["grep"]:?} -q .; then
		if ! ${ove_cmd2pathname["mkdir"]:?} -p "${wd}"/projects/${proj}; then
			return 1
		elif ! ${ove_cmd2pathname["cp"]:?} -ar ${OVE_OWEL_DIR}/projects/${proj}/* "${wd}"/projects/${proj}; then
			return 1
		fi
		for f in "${wd}"/projects/"${proj}"/*; do
			${ove_cmd2pathname["git"]:?} -C "${wd}" diff /dev/null ${f/${OVE_OWEL_TMP_DIR}\/export\/} >> "${wd}"/${proj}.patch
		done
	fi

	return 0
}

function ove_export {
	local c
	local _end
	local f
	local proj
	local projects
	local proj_index
	local proj_path
	local repo_path
	local s
	local _start
	local wd="${OVE_OWEL_TMP_DIR}/export"
	declare -A cfg_list

	${ove_cmd2pathname["mkdir"]:?} -p "${wd}"
	${ove_cmd2pathname["find"]:?} "${wd}" -maxdepth 1 -name '*.patch' -exec rm {} \;

	if [ "$#" -eq 0 ]; then
		projects="${OVE_PROJECT_LIST}"
	else
		projects="${*}"
	fi

	# preparations
	true > "${wd}"/revtab
	true > "${wd}"/projs
	true > "${wd}"/.oveconfig
	(cd "${wd}" || exit 1
	if [ -d .git ]; then
		${ove_cmd2pathname["rm"]:?} -rf .git
	fi
	${ove_cmd2pathname["git"]:?} init -q .
	${ove_cmd2pathname["git"]:?} add revtab projs .oveconfig
	${ove_cmd2pathname["git"]:?} commit -m "export: revtab projs" -q)

	for proj in ${projects}; do
		echo $proj

		_start=$(${ove_cmd2pathname["grep"]:?} -n '^[a-zA-Z0-9_]\+:' ${OVE_OWEL_DIR}/projs |
			${ove_cmd2pathname["grep"]:?} -A1 "^[0-9]\+:${proj}:" |
			${ove_cmd2pathname["sed"]:?} -e 's,#.*$,,g')
		if [ "$_start" = "" ]; then
			ove_echo_warning_noprefix "project '$proj' not found in '$OVE_OWEL_DIR/projs'"
			continue
		fi

		true > "${wd}"/revtab
		true > "${wd}"/projs

		if [ "$(printf "%s\n" $_start | ${ove_cmd2pathname["wc"]:?} -l)" -eq 1 ]; then
			_end=$(${ove_cmd2pathname["wc"]:?} -l < "${OVE_OWEL_DIR}/projs")
		else
			_end=$(printf "%s\n" $_start | ${ove_cmd2pathname["tail"]:?} -1 | ${ove_cmd2pathname["cut"]:?} -d: -f1)
			((_end--))
		fi
		_start="${_start%%:*}"

		# projs
		echo > "${wd}"/projs
		${ove_cmd2pathname["sed"]:?} -n "${_start},${_end}p" ${OVE_OWEL_DIR}/projs >> "${wd}"/projs
		# shellcheck disable=SC2016
		${ove_cmd2pathname["sed"]:?} -i -e '${/^$/d;}' "${wd}"/projs

		if ! ove_export_create_proj_patch "${proj}" "${wd}"; then
			return 1
		fi
		${ove_cmd2pathname["git"]:?} -C "${wd}" diff -U0 projs >> "${wd}"/${proj}.patch
		ove_modify_patch "${wd}"/${proj}.patch "projs"

		# revtab
		proj_index=${ove_projects_name2index[${proj}]}
		proj_path=${ove_projects_path[${proj_index}]}
		while true; do
			if [ "${proj_path}" = "" ]; then
				break
			fi
			repo_path=$(printf "%s\n" ${OVE_REPO_LIST} | ${ove_cmd2pathname["grep"]:?} ^${proj_path}$)
			if [ "${repo_path}" != "" ]; then
				i=${ove_revtab_name2index[${repo_path/${OVE_BASE_DIR}\/}]}
				printf "%s %s %s %s\n" \
					${ove_revtab_git_name[${i}]} \
					${ove_revtab_fetch_url[${i}]} \
					${ove_revtab_push_url[${i}]} \
					${ove_revtab_rev[${i}]} >>"${wd}"/revtab
				${ove_cmd2pathname["git"]:?} -C "${wd}" diff revtab >> "${wd}"/${proj}.patch
				ove_modify_patch "${wd}"/${proj}.patch "revtab"
				break
			fi
			proj_path="${proj_path%/*}"
		done

		# scripts
		${ove_cmd2pathname["mkdir"]:?} -p "${wd}"/scripts
		for s in $(ove-proj2val "${proj}" scripts 2> /dev/null); do
			if [ ! -s "${OVE_OWEL_DIR}/scripts/${s}" ]; then
				continue
			elif ! ${ove_cmd2pathname["cp"]:?} -a "${OVE_OWEL_DIR}/scripts/${s}" "${wd}/scripts/${s}"; then
				return 1
			fi
			f="${wd}/scripts/${s}"
			${ove_cmd2pathname["git"]:?} -C "${wd}" diff /dev/null ${f/${OVE_OWEL_TMP_DIR}\/export\/} >> "${wd}"/${proj}.patch
		done

		# config
		for c in $(ove-proj2val "${proj}" config 2> /dev/null); do
			if [ "${cfg_list["${c}"]+isset}" ]; then
				continue
			elif [ "${!c}" = "" ]; then
				continue
			fi
			echo "$c ${!c}" >> "${wd}/.oveconfig"
			cfg_list[$c]=1
		done
		if [ -s "${wd}/.oveconfig" ]; then
			f="${wd}/.oveconfig"
			${ove_cmd2pathname["git"]:?} -C "${wd}" diff ${f/${OVE_OWEL_TMP_DIR}\/export\/} >> "${wd}"/${proj}.patch
			ove_modify_patch "${wd}"/${proj}.patch ".oveconfig"
			true > "${wd}/.oveconfig"
		fi
	done

	# common
	if ! ove_export_create_proj_patch "common" "${wd}"; then
		return 1
	fi

	${ove_cmd2pathname["rm"]:?} -rf "${wd}"/{projs,revtab,projects,.git,scripts,.oveconfig}
}

# export:[project...|tag...]:export project(s):CORE
function ove-export {
	ove_entry || return

	local args="$*"
	local name
	local proj_list
	local rev

	if [ $# -eq 0 ]; then
		if ! ove_export; then
			return 1
		fi
	else
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi

		proj_list="$(ove_get_deps_recursive $proj_list) $proj_list"
		if ! ove_export $(printf "%s\n" "$(ove_uniq $proj_list)" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}); then
			return 1
		fi
	fi

	if [ "$(${ove_cmd2pathname["find"]:?} "${OVE_OWEL_TMP_DIR}/export" -maxdepth 1 -name '*.patch' -print -quit)" = "" ]; then
		ove_echo_error_noprefix "no project(s) exported"
		return 1
	fi

	name="${OVE_BASE_DIR}/${OVE_OWEL_NAME}"
	# shellcheck disable=SC2016
	rev=$(ove-describe ${OVE_OWEL_NAME} | ${ove_cmd2pathname["awk"]:?} '{print $2}')
	if [ "$rev" != "" ]; then
		name+="-${rev}"
	fi

	if [ $# -eq 1 ]; then
		name+="-${args}"
	fi
	name+=".tar.bz2"
	if ! ${ove_cmd2pathname["touch"]:?} ${OVE_OWEL_TMP_DIR}/export/${OVE_SHA:?}-export; then
		return 1
	elif ! ${ove_cmd2pathname["tar"]:?} -C "${OVE_OWEL_TMP_DIR}/export" -cjf "${name}" --owner=0 --group=0 .; then
		return 1
	fi
	echo "${name}"

	return 0
}

function ove_patch_one_project {
	local f
	local proj

	f="$1"
	proj=${1##*/}
	proj=${proj/.patch/}

	if [ "${proj}" != "common" ]; then
		echo "${proj}"
	fi
	if ${ove_cmd2pathname["grep"]:?} -q ^$proj: ${OVE_OWEL_DIR}/projs; then
		return
	fi

	ove_repo_cmd ${OVE_OWEL_DIR} apply --whitespace=nowarn "${f}" 2> /dev/null
}

# import:file:import project(s), see export:CORE
function ove-import {
	ove_entry || return

	local f
	local lines
	local n
	local patch
	local proj
	local repo
	local ret=0
	local out

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	fi

	f="$1"
	if [ ! -e "${f}" ]; then
		ove_echo_error_noprefix "'${f}' not found"
		return 1
	elif [ ! -s "${f}" ]; then
		ove_echo_error_noprefix "'${f}' file size is 0"
		return 1
	elif ! ${ove_cmd2pathname["file"]:?} "${f}" | ${ove_cmd2pathname["grep"]:?} -q "bzip2 compressed data"; then
		ove_echo_error_noprefix "'${f}' is not a bzip2 compressed data file"
		return 1
	# sanity check archive
	elif ! ${ove_cmd2pathname["tar"]:?} -tf "$f" | ${ove_cmd2pathname["grep"]:?} -q '\./[0-9a-f]\+-export$'; then
		ove_echo_error_noprefix "archive '$f' was not created with 'ove export'"
		return 1
	elif ! ${ove_cmd2pathname["mkdir"]:?} -p "${OVE_OWEL_TMP_DIR}/import"; then
		return 1
	fi

	# clean up
	${ove_cmd2pathname["find"]:?} "${OVE_OWEL_TMP_DIR}/import" -maxdepth 1 -name '*.patch' -exec rm {} \;

	if ! ${ove_cmd2pathname["tar"]:?} -C "${OVE_OWEL_TMP_DIR}/import" --exclude './*-export' -xf "${f}" --no-same-owner; then
		return 1
	fi

	n=0

	if [ ! -s ${OVE_OWEL_DIR}/projs ]; then
		# create projs
		echo "---" > ${OVE_OWEL_DIR}/projs
		n=1
	fi

	if [ ! -s ${OVE_OWEL_DIR}/revtab ] && \
		${ove_cmd2pathname["grep"]:?} \
			-q \
			' b/revtab$' \
			"${OVE_OWEL_TMP_DIR}/import/"*; then
		# create revtab
		true > ${OVE_OWEL_DIR}/revtab
	fi

	for patch in "${OVE_OWEL_TMP_DIR}/import/"*.patch; do
		if ! ove_patch_one_project "$patch"; then
			((ret++))
			continue
		fi
	done

	if [ $ret -eq 0 ] && [ $n -eq 1 ]; then
		# remove empty 2nd line in 'projs'
		${ove_cmd2pathname["sed"]:?} -i -e '2d' ${OVE_OWEL_DIR}/projs
	fi

	# remove revtab duplicates
	# shellcheck disable=SC2016
	if ! out=$(ove_revtab_validate 2> /dev/null); then
		lines=$(r_prev=; while read -r line; do
			n=${line%%:*}
			repo=${line##*:}
			if [ "$r_prev" = "" ]; then
				r_prev="$repo"
				continue
			elif [ "$r_prev" = "$repo" ]; then
				echo $n
				continue
			elif [ "$r_prev" != "$repo" ]; then
				r_prev="$repo"
				continue
			fi
		done <<<"$(printf "${out}" | ${ove_cmd2pathname["awk"]:?} '{print $1}')")
		${ove_cmd2pathname["sed"]:?} -i -e "$(printf "%sd;" $lines)" "${OVE_OWEL_DIR}/revtab"
	fi

	return ${ret}
}

function ove_set_proj_mask {
	local a
	local b

	for a in "$@"; do
		b=${a:1}
		if [[ $a == +* ]] && [[ -v ove_projects_name2index[${b}] ]]; then
			unset 'proj_mask[${b}]'
		elif [[ $a == -* ]] && [[ -v ove_projects_name2index[${b}] ]]; then
			proj_mask[${b}]=1
		fi
	done
}

function ove_parse_project_args {
	local a
	local b
	local delete
	local merge
	local c
	declare -a p

	for a in "$@"; do
		merge=0
		delete=0
		if [[ $a == +* ]]; then
			c=${a:1}
			merge=1
		elif [[ $a == -* ]]; then
			c=${a:1}
			delete=1
		else
			c=$a
			merge=0
		fi

		if [ $delete -eq 1 ]; then
			if [ ${#p[*]} -eq 0 ]; then
				continue
			fi
			# is 'c' a tag?
			if [[ -v ove_projects_tags[$c] ]]; then
				mapfile -t p <<<"$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -1 -3 \
					<(printf "%s\n" ${ove_projects_tags[$c]} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}) \
					<(printf "%s\n" "${p[@]}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}))"
			else
				mapfile -t p <<<"$(printf "%s\n" "${p[@]}" | ${ove_cmd2pathname["grep"]:?} -v ^$c$)"
			fi
			continue
		fi

		# just append if 'c' is NOT a tag
		if [[ ! -v ove_projects_tags[$c] ]]; then
			p+=("$c")
			continue
		fi

		# if 'c' is a tag, we want to merge and we have some previous projects to merge with
		if [ $merge -eq 1 ] && [ ${#p[*]} -ge 1 ]; then
			# keep projects that are common between previous results ('p') and projects pointed by the new tag ('c')
			mapfile -t p <<<"$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -1 -2 \
				<(printf "%s\n" ${ove_projects_tags[$c]} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}) \
				<(printf "%s\n" "${p[@]}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}))"

			if [ ${#p[*]} -eq 0 ] || [ "${p[0]}" = "" ]; then
				ove_echo_error_noprefix "no projects found"
				return 1
			fi
		else
			for b in ${ove_projects_tags[$c]}; do
				p+=("$b")
			done
		fi
	done

	if [ ${#p[*]} -eq 0 ] || [ "${p[0]}" = "" ]; then
		ove_echo_error_noprefix "no projects found"
		return 1
	fi
	echo "${p[*]}"

	return 0
}

function ove_validate_project_list {
	local a
	declare -a p

	if ! read -a p -r <<<$(ove_parse_project_args "$@"); then
		return 1
	fi

	for a in "${p[@]}"; do
		if ! [[ -v ove_projects_name2index[${a}] ]]; then
			ove_echo_error_noprefix "unknown project '${a}'"
			return 1
		fi
	done

	echo "${p[*]}"

	return 0
}

function ove_build_pre {
	local a
	local p
	local proj_list
	local q
	local re
	local repos

	if [ $# -eq 0 ]; then
		if [ -n "${OVE_PROJECT_LIST_BUILDABLE+x}" ] && \
			[ "${OVE_PROJECT_LIST_BUILDABLE}" != "${OVE_PROJECT_LIST}" ]; then
			ove_echo_error_noprefix "'$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -3 \
				<(printf "%s\n" ${OVE_PROJECT_LIST}) \
				<(printf "%s\n" ${OVE_PROJECT_LIST_BUILDABLE}) |
				${ove_cmd2pathname["xargs"]:?})' is not ${OVE_PROJECT_COMMANDS// /\/}-able. Try: 'ove fetch'"
			return 1
		fi
	else
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi

		for a in ${proj_list}; do
			if ! [[ -v ove_projects_name2index[$a] ]]; then
				ove_echo_error_noprefix "unknown project '$a'"
				return 1
			fi

			if [ -n "${OVE_PROJECT_LIST_BUILDABLE+x}" ]; then
				re=\\b$a\\b
				if ! [[ "${OVE_PROJECT_LIST_BUILDABLE}" =~ ${re} ]]; then
					for p in $(ove_get_paths_recursive $a | ${ove_cmd2pathname["xargs"]:?} -n1 | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u); do
						if ove_dir_is_repo "${p}"; then
							continue
						fi
						for q in ${OVE_REPO_LIST}; do
							if [[ ${p}/ == *"${q}/"* ]]; then
								if ! ove_dir_is_repo "${q}"; then
									repos+="$(ove_repo2shortpath ${q}) "
								fi
							fi
						done
					done
					if [ "${repos}" != "" ]; then
						repos=$(printf "%s\n" ${repos} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u | ${ove_cmd2pathname["xargs"]:?})
						if [ "${OVE_AUTO_CLONE}" = "1" ]; then
							if ! ove-fetch $repos; then
								return 1
							fi
						else
							ove_echo_error_noprefix "'$a' is not a ${OVE_PROJECT_COMMANDS// /\/}-able project. Try: 'ove fetch ${repos}'"
							return 1
						fi
					fi
				fi
			fi
		done
	fi

	# create stage/archive directories if needed
	if [ ! -d "${OVE_STAGE_DIR}" ]; then
		${ove_cmd2pathname["mkdir"]:?} -p "${OVE_STAGE_DIR}"
	fi
	if [ ! -d "${OVE_ARCHIVE_DIR}" ]; then
		${ove_cmd2pathname["mkdir"]:?} -p "${OVE_ARCHIVE_DIR}"
	fi

	return 0
}

function ove_build_post {
	local f

	if [ -d ${OVE_STAGE_DIR} ] && \
		[ "$(${ove_cmd2pathname["find"]:?} ${OVE_STAGE_DIR} -maxdepth 1)" = "${OVE_STAGE_DIR}" ]; then
		f+="${OVE_STAGE_DIR} "
	fi

	if [ -d ${OVE_ARCHIVE_DIR} ] && \
		[ "$(${ove_cmd2pathname["find"]:?} ${OVE_ARCHIVE_DIR} -maxdepth 1)" = "${OVE_ARCHIVE_DIR}" ]; then
		f+="${OVE_ARCHIVE_DIR} "
	fi

	if [ "${f}" != "" ]; then
		if ! ${ove_cmd2pathname["rmdir"]:?} ${f}; then
			ove_echo_fatal_noprefix "'rmdir ${f}' failed"
		fi
	fi

	return 0
}

function ove_get_build_list {
	local b

	b="$(ove_get_deps_recursive "$@") $*"
	b="$(printf "%s\n" ${b} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u | ${ove_cmd2pathname["xargs"]:?})"

	echo ${b}
}

# list-tags: :list project tags:CORE
function ove-list-tags {
	ove_entry || return
	local t

	if [ ${#ove_projects_tags[*]} -eq 0 ]; then
		return 0
	fi

	for t in ${!ove_projects_tags[*]}; do
		printf "%s|%s\n" $t "${ove_projects_tags[$t]}"
	done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | ${ove_cmd2pathname["column"]:?} -t -s'|'
}

# list-deps:[project...|tag...]:list dependencies for all/specified project(s):CORE
function ove-list-deps {
	ove_list_helper "${FUNCNAME[0]/ove-list-}" "$@"
}

# list-needs:[project...|tag...]:list OS packages needs for all/specified project(s):CORE
function ove-list-needs {
	ove_list_helper "${FUNCNAME[0]/ove-list-}" "$@"
}

# list-path:[project...|tag...]:list paths for all/specified project(s):CORE
function ove-list-path {
	ove_list_helper "${FUNCNAME[0]/ove-list-}" "$@"
}

function ove_list_helper {
	ove_entry || return

	local b
	local build_list
	local i
	local n
	local -n p
	local proj_list
	local re
	local result_list
	declare -A proj_mask

	p="ove_projects_${1}"
	shift

	if [ $# -ge 1 ]; then
		if ! proj_list=$(ove_validate_project_list "${@}"); then
			return 1
		fi

		build_list="$(ove_get_build_list ${proj_list})"
		ove_set_proj_mask "$@"
	fi

	for b in ${OVE_BUILD_ORDER}; do
		if [ $# -ge 1 ]; then
			re=\\b${b}\\b
			if [[ -v proj_mask[${b}] ]]; then
				continue
			elif ! [[ "${build_list}" =~ ${re} ]]; then
				continue
			fi
		fi

		i=${ove_projects_name2index[${b}]}
		for n in ${p[${i}]}; do
			result_list+="${n} "
		done
	done

	if [ "${result_list}" != "" ]; then
		printf "%s\n" ${result_list} | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
	fi

	return 0
}

# install-pkg-os:pkg...:install OS packages:CORE
function ove-install-pkg-os {
	ove_entry || return

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	elif ! ove_install_packages "${@}"; then
		return 1
	fi
}

# install-pkg:[project...|tag...]:install needed OS packages for all/specified project(s):CORE
function ove-install-pkg {
	ove_entry || return

	local pack_list

	if ! pack_list=$(ove-list-needs "${@}"); then
		return 1
	elif [ "${pack_list}" = "" ]; then
		return 0
	elif ! ove_install_packages ${pack_list}; then
		return 1
	fi
}

# buildme:[project...|tag...]:build project(s) from scratch (=bootstrap, configure, build, install):BUILD
function ove-buildme {
	ove_entry || return

	local b
	local build_list
	local p
	local proj_list
	local re
	declare -A proj_mask

	if ! ove_build_pre "$@"; then
		return 1
	fi
	trap ove_build_post EXIT

	# install packages
	if ! ove-install-pkg "$@"; then
		return 1
	fi

	if [ $# -ge 1 ]; then
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi

		build_list="$(ove_get_build_list ${proj_list})"
		ove_set_proj_mask "$@"
	fi

	for p in ${OVE_BUILDME_PRE_STEPS}; do
		for b in ${OVE_BUILD_ORDER}; do
			if [ $# -ge 1 ]; then
				re=\\b${b}\\b
				if [[ -v proj_mask[${b}] ]]; then
					continue
				elif ! [[ "${build_list}" =~ ${re} ]]; then
					continue
				fi
			fi

			if ! ove_project_has_step "${b}" "${p}"; then
				continue
			elif [ "$(type -t ove-${p})" = "function" ] && \
				! eval ove-${p} ${b} ${OVE_REDIRECT_OUTPUT}; then
				ove_echo_error_noprefix "${FUNCNAME[0]}: ${p} ${b} failed"
				return 1
			fi
		done
	done

	for b in ${OVE_BUILD_ORDER}; do
		if [ $# -ge 1 ]; then
			re=\\b${b}\\b
			if [[ -v proj_mask[${b}] ]]; then
				continue
			elif ! [[ "${build_list}" =~ ${re} ]]; then
				continue
			fi
		fi

		for p in ${OVE_BUILDME_STEPS}; do
			if [ "$(type -t ove-${p})" = "function" ] && \
				! eval ove-${p} ${b} ${OVE_REDIRECT_OUTPUT}; then
				ove_echo_error_noprefix "${FUNCNAME[0]}: ove-${p} ${b} failed"
				return 1
			fi
		done
	done

	return 0
}

function ove_buildme_parallel_shell {
	local b
	local build_list
	local dep
	local inotify_max_user_instances
	local p
	local proj_list
	local pid
	local pids
	local re
	local wait_for_deps
	declare -A proj_mask

	if [ ! -e /proc ]; then
		ove_echo_error_noprefix "procfs mount point '/proc' is missing"
		return 1
	fi

	if [ $# -ge 1 ]; then
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi

		build_list="$(ove_get_build_list ${proj_list})"
		ove_set_proj_mask "$@"
	fi

	for p in ${OVE_BUILDME_PRE_STEPS}; do
		for b in ${OVE_BUILD_ORDER}; do
			if [ $# -ge 1 ]; then
				re=\\b${b}\\b
				if [[ -v proj_mask[${b}] ]]; then
					continue
				elif ! [[ "${build_list}" =~ ${re} ]]; then
					continue
				fi
			fi

			if ! ove_project_has_step "${b}" "${p}"; then
				continue
			fi

			{
				if [ "$(type -t ove-${p})" = "function" ] && \
					! eval ove-${p} ${b} ${OVE_REDIRECT_OUTPUT}; then
					ove_echo_error_noprefix "${FUNCNAME[0]}: ${p} ${b} failed"
					kill -USR1 $$
				fi
			} &
			pids+="$! "
		done
	done

	wait ${pids}
	pids=""

	# pids db
	declare -A pids_db=()

	if [ -e /proc/sys/fs/inotify/max_user_instances ]; then
		inotify_max_user_instances=$(($(${ove_cmd2pathname["cat"]:?} /proc/sys/fs/inotify/max_user_instances) - 20))
	else
		inotify_max_user_instances=1024
	fi
	for b in ${OVE_BUILD_ORDER}; do
		if [ $# -ge 1 ]; then
			re=\\b${b}\\b
			if [[ -v proj_mask[${b}] ]]; then
				continue
			elif ! [[ "${build_list}" =~ ${re} ]]; then
				continue
			fi
		fi

		wait_for_deps=""
		for dep in $(ove_get_deps_recursive ${b}); do
			if [[ -v proj_mask[${dep}] ]]; then
				continue
			elif ! [ -e /proc/${pids_db[${dep}]} ]; then
				pids_db[${dep}]=""
				continue
			fi

			wait_for_deps+="${pids_db[${dep}]} "
		done

		{
			for p in ${wait_for_deps}; do
				${ove_cmd2pathname["tail"]:?} -s 0.01 --pid=${p} -f /dev/null &
			done
			if [ "${wait_for_deps}" != "" ]; then
				wait
			fi

			for p in ${OVE_BUILDME_STEPS}; do
				if [ "$(type -t ove-${p})" = "function" ] && \
					! eval ove-${p} ${b} ${OVE_REDIRECT_OUTPUT}; then
					ove_echo_error_noprefix "${FUNCNAME[0]}: ${p} ${b} failed"
					kill -USR1 $$
				fi
			done
		} &
		pid=$!
		pids_db[${b}]=${pid}
		pids+=" ${pid}"

		while true; do
			if [ $(${ove_cmd2pathname["pgrep"]:?} -f 'tail -s 0.01' | ${ove_cmd2pathname["wc"]:?} -l) -gt ${inotify_max_user_instances} ]; then
				${ove_cmd2pathname["sleep"]:?} 0.1
				continue
			fi
			break
		done
	done

	wait ${pids}

	return 0
}

function ove_buildme_parallel_make {
	local b
	local build_list
	local dep
	local deps
	local makefile
	local p
	local proj_list
	local phony
	local pre_steps
	local re
	declare -A pre_steps_projects
	# shellcheck disable=SC2034
	declare -A proj_mask

	makefile="${OVE_OWEL_TMP_DIR:?}/Makefile"
	${ove_cmd2pathname["cat"]:?} > "${makefile}" << EOF
SHELL := ${ove_cmd2pathname["bash"]:?}
PID := \$(shell echo \$\$PPID)
PREFIX := @MAKEFLAGS="\${OVE_MAKEFLAGS}"
SUFFIX := kill -TERM \$(PID)
define BUILD =
EOF
	for p in ${OVE_BUILDME_STEPS}; do
		if [ "$(type -t ove-${p})" = "function" ]; then
			echo -e "\t\$(PREFIX) ove-${p} \$@ || \$(SUFFIX)" >> ${makefile}
		fi
	done
	echo "endef" >> ${makefile}

	if [ $# -ge 1 ]; then
		if ! proj_list=$(ove_validate_project_list "$@"); then
			return 1
		fi

		build_list="$(ove_get_build_list ${proj_list})"
		ove_set_proj_mask "$@"
	fi

	for p in ${OVE_BUILDME_PRE_STEPS}; do
		for b in ${OVE_BUILD_ORDER}; do
			if [ $# -ge 1 ]; then
				re=\\b${b}\\b
				if [[ -v proj_mask[${b}] ]]; then
					continue
				elif ! [[ "${build_list}" =~ ${re} ]]; then
					continue
				fi
			fi

			if ! ove_project_has_step "${b}" "${p}"; then
				continue
			fi

			echo "${b}_${p}:" >> "${makefile}"
			phony+=" ${b}_$p"
			echo -e "\t\$(PREFIX) ove-${p} ${b} || \$(SUFFIX)" >> "${makefile}"
			pre_steps_projects["${b}"]+="${b}_${p} "
		done
	done

	for b in ${OVE_BUILD_ORDER}; do
		if [ $# -ge 1 ]; then
			re=\\b${b}\\b
			if [[ -v proj_mask[${b}] ]]; then
				continue
			elif ! [[ "${build_list}" =~ ${re} ]]; then
				continue
			fi
		fi

		deps=
		for dep in $(ove_get_deps_recursive ${b}); do
			if [[ -v proj_mask[${dep}] ]]; then
				continue
			fi
			deps+=" $dep"
		done
		if [ "${deps}" != "" ]; then
			deps="$(ove_uniq ${deps})"
			deps="$(printf "%s " ${deps})"
			deps=${deps::-1}
		fi
		pre_steps="${pre_steps_projects[${b}]}"
		if [ "${pre_steps}" != "" ]; then
			pre_steps=${pre_steps::-1}
		fi
		if [ "${deps}" = "" ] && [ "${pre_steps}" = "" ]; then
			echo "$b:" >> "${makefile}"
		elif [ "${deps}" = "" ] && [ "${pre_steps}" != "" ]; then
			echo "$b: ${pre_steps}" >> "${makefile}"
		elif [ "${deps}" != "" ] && [ "${pre_steps}" = "" ]; then
			echo "$b: ${deps}" >> "${makefile}"
		else
			echo "$b: ${deps} ${pre_steps}" >> "${makefile}"
		fi
		echo -e "\t\$(BUILD)" >> "${makefile}"
		phony+=" $b"
	done

	{ echo ".PHONY:$phony"; \
		echo ".DEFAULT_GOAL := all"; \
		echo "all:$phony"; } >> "${makefile}"

	eval ${ove_cmd2pathname["make"]:?} -f "${makefile}" "${OVE_MAKEFLAGS}"
	return $?
}

# buildme-parallel:[project...|tag...]:build project(s) from scratch (=bootstrap, configure, build, install):BUILD
function ove-buildme-parallel {
	ove_entry || return

	if ! ove_build_pre "$@"; then
		return 1
	fi
	trap ove_build_post EXIT

	if ! ove-install-pkg "$@"; then
		return 1
	fi

	if command -v make > /dev/null; then
		if [[ "${OVE_OS_KERNEL,,}" = *bsd* ]] && \
			! command -v gmake > /dev/null; then
			ove_command_not_found "gmake"
			return 1
		fi
		ove_buildme_parallel_make "$@"
	else
		ove_buildme_parallel_shell "$@"
	fi
	return $?
}

# diff-check:[options]:git diff --check [options]:CORE
function ove-diff-check {
	ove_entry || return

	local cmd

	cmd="echo \${PWD}; ove_repo_cmd \${repo} '--no-pager diff' --check $* -- \$(ove_repo_cmd \${repo} diff --name-only)"
	ove_revtab_forall "${cmd}"
}

# list-repositories:[ahead|behind]:list all git repositories or list repositories that are ahead/behind:CORE
function ove-list-repositories {
	ove_entry || return

	local i
	local str
	local url

	if [ $# -eq 0 ]; then
		:
	elif [ $# -eq 1 ] && [ "$1" = "behind" ]; then
		ove_list_repositories "behind"
		return 0
	elif [ $# -eq 1 ] && [ "$1" = "ahead" ]; then
		ove_list_repositories "ahead"
		return 0
	else
		ove_command_usage
		return 1
	fi

	i=0

	while ((i < ove_revtab_num_repositories)); do
		str+="${ove_revtab_git_name[${i}]} ${ove_revtab_fetch_url[${i}]} ${ove_revtab_push_url[${i}]} ${ove_revtab_rev[${i}]}\n"
		(( i+=1 ))
	done

	url=$(ove_repo_cmd "${OVE_OWEL_DIR}" "config" --get remote.origin.url)
	if [ "${url}" != "" ]; then
		str+="${OVE_OWEL_NAME} ${url} ${url} $(ove_repo_cmd "${OVE_OWEL_DIR}" "rev-parse" --abbrev-ref HEAD 2> /dev/null)\n"
	else
		str+="${OVE_OWEL_NAME} noremote noremote $(ove_repo_cmd "${OVE_OWEL_DIR}" "rev-parse" --abbrev-ref HEAD 2> /dev/null)\n"
	fi

	printf "${str}" | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["column"]:?} -t
}

# env:[pattern]:show OVE environment variables:CORE
function ove-env {
	ove_entry || return

	local e
	local str
	local v

	if [ $# -eq 0 ]; then
		v=$(compgen -A variable OVE_)
	else
		v=$(compgen -A variable OVE_ | \
			${ove_cmd2pathname["grep"]:?} -i $1)
	fi

	for e in ${v}; do
		str+="${e}#${!e/\\/\\\\}\n"
	done

	printf "${str}" | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["column"]:?} -t -s'#'
}

function ove_entry {
	local f

	if [[ ${FUNCNAME[*]} == *"ove_main"* ]]; then
		return
	fi

	if ! ove_get_base_dir &> /dev/null; then
		return 1
	fi

	for f in "${FUNCNAME[@]}"; do
		if [ "${f}" = "source" ] || [ "${f}" = "main" ]; then
			continue
		elif [ "$(type -t ${f})" != "function" ]; then
			ove_echo_stderr_noprefix "$f: command not found"
			return 127
		fi
	done

	# keep this early
	if ! declare -p ove_cmd2pathname &> /dev/null; then
		ove_externals_init
	fi

	if ! [ -v ove_revtab_fetch_url ]; then
		ove_revtab_init
	fi

	if ! [ -v ove_projects_name ]; then
		ove_projects_init
	fi

	if ! declare -p ove_scripts_paths &> /dev/null; then
		ove_scripts_init
	fi

	if ! declare -p ove_hooks_post &> /dev/null; then
		ove_hooks_init
	fi

	if ! declare -p ove_revtab_git_cmd_opts &> /dev/null; then
		ove_git_command_options_init
	fi

	ove_update_terminal_stats
}

# status:[git...]:git status -zbs -uno for all/specified repositories:CORE
function ove-status {
	ove_entry || return

	# turn off monitor mode to get rid of "Done" messages
	set +m

	ove_revtab_status "$@" | \
		${ove_cmd2pathname["grep"]:?} -v '^\['

	# turn on monitor mode
	set -m
}

# news:[git...]:list upstream changes for all/specified repositories:CORE
function ove-news {
	ove_entry || return

	ove-behind "$@"
}

# behind:[git...]:list upstream changes for all/specified repositories:CORE
function ove-behind {
	ove_entry || return

	if [ -w "${OVE_OWEL_STATE_DIR}" ]; then
		ove_revtab_status_parse behind "$@" | ${ove_cmd2pathname["tee"]:?} ${OVE_OWEL_STATE_DIR}/revtab-news
	else
		ove_revtab_status_parse behind "$@"
	fi
}

# show-behind:[git...]:run 'ove show' on upstream changes for all/specified repositories:CORE
function ove-show-behind {
	ove_entry || return

	ove-show-news "$@"
}

# show-news:[git...]:run 'ove show' on upstream changes for all/specified repositories:CORE
function ove-show-news {
	ove_entry || return

	local less_opt
	local line
	local re_a
	local re_b
	local repo
	local sha

	# refresh news
	ove-news "$@" > /dev/null
	if [ ! -s ${OVE_OWEL_STATE_DIR}/revtab-news ]; then
		return
	fi

	# remove color codes
	${ove_cmd2pathname["sed"]:?} -i \
		-r \
		-e "s/\x1b\[0;3[0-9];7m//g" \
		-e "s/\x1b\[[0-9]+m//g" \
		-e "s/\x1b\[m//g" ${OVE_OWEL_STATE_DIR}/revtab-news

	re_a=": [0-9]+ new commit"
	re_b="^[a-f0-9]+"
	while read -r line; do
		if [[ "${line}" =~ ${re_a} ]]; then
			repo="${line%%:*}"
		elif [[ "${line}" =~ ${re_b} ]]; then
			clear
			sha=${line%% *}
			if [ ${OVE_LESS_MORE_OPTIONS} -eq 1 ]; then
				less_opt="-X -R -Ps${repo} ${sha}"
			else
				less_opt="-R"
			fi
			LESS="${less_opt}" ove_repo_cmd ${OVE_BASE_DIR}/${repo} '-p show' --first-parent $sha --
		fi
	done<${OVE_OWEL_STATE_DIR}/revtab-news
}

# ahead:[git...]:list local commits not yet published for all/specified repositories:CORE
function ove-ahead {
	ove_entry || return

	if [ -w "${OVE_OWEL_STATE_DIR}" ]; then
		ove_revtab_status_parse ahead "$@" | ${ove_cmd2pathname["tee"]:?} ${OVE_OWEL_STATE_DIR}/revtab-ahead
	else
		ove_revtab_status_parse ahead "$@"
	fi
}

# show-ahead:[git...]:run 'ove show' on local commits not yet published for all/specified repositories:CORE
function ove-show-ahead {
	ove_entry || return

	local sha_list

	# refresh ahead
	ove-ahead "$@" > /dev/null

	sha_list="$(${ove_cmd2pathname["grep"]:?} -o '^[a-f0-9]\+' ${OVE_OWEL_STATE_DIR}/revtab-ahead | ${ove_cmd2pathname["tac"]:?})"
	if [ "${sha_list}" = "" ]; then
		return
	fi

	ove-show ${sha_list}
}

# reset-ahead:[git...]:git reset --hard HEAD~N where N is number of commits ahead for all or specified repositories, USE WITH CARE:CORE
function ove-reset-ahead {
	ove_entry || return

	ove-ahead "$@" | \
		${ove_cmd2pathname["sed"]:?} -r \
		-e "s/\x1b\[0;3[0-9];7m//g" \
		-e "s/\x1b\[[0-9]+m//g" \
		-e "s/\x1b\[m//g" | \
		${ove_cmd2pathname["grep"]:?} --color=never ': [0-9]\+ new commit' | \
		while IFS=' ' read -r repo n foo bar; do
			repo=${repo/:/}
			ove_repo_cmd ${OVE_BASE_DIR}/${repo} reset --hard HEAD~${n} |& ${ove_cmd2pathname["sed"]:?} -e "s,^,${repo}: ,g"
		done
}

# rebase-autosquash:[git...]:run 'git rebase -i HEAD~N --autosquash' where N is the number of local commits not yet published:CORE
function ove-rebase-autosquash {
	ove_entry || return

	if ${ove_cmd2pathname["git"]:?} help config &> /dev/null; then
		if ! ${ove_cmd2pathname["git"]:?} help config | ${ove_cmd2pathname["grep"]:?} -q GIT_SEQUENCE_EDITOR; then
			ove_echo_error_noprefix "'GIT_SEQUENCE_EDITOR' not available, too old git version?"
			return 1
		fi
	fi

	ove-ahead "$@"
	ove-ahead "$@" | \
		${ove_cmd2pathname["sed"]:?} -r \
		-e "s/\x1b\[0;3[0-9];7m//g" \
		-e "s/\x1b\[[0-9]+m//g" \
		-e "s/\x1b\[m//g" | \
		${ove_cmd2pathname["grep"]:?} --color=never ': [0-9]\+ new commit' | \
		while IFS=' ' read -r repo n foo bar; do
			repo=${repo/:/}
			ove_echo_yellow_noprefix ${repo}
			GIT_SEQUENCE_EDITOR=: ove_repo_cmd ${OVE_BASE_DIR}/${repo} rebase -i HEAD~${n} --autosquash |& ${ove_cmd2pathname["sed"]:?} -e "s/^/${repo}: /g"
			if [ ${PIPESTATUS[0]} -ne 0 ]; then
				ove_echo_error_noprefix "rebase failed for '${repo}'"
				return 1
			fi
		done
	ove-ahead "$@"
}

# format-patch:[name]:create a bz2 archive for all local commits not yet published:CORE
function ove-format-patch {
	ove_entry || return

	local d
	local f

	d=$(${ove_cmd2pathname["mktemp"]:?} -d -p ${OVE_OWEL_TMP_DIR})
	${ove_cmd2pathname["mkdir"]:?} -p ${d}
	${ove_cmd2pathname["find"]:?} ${d} -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} \;

	ove-ahead | \
		${ove_cmd2pathname["sed"]:?} -r \
		-e "s/\x1b\[0;3[0-9];7m//g" \
		-e "s/\x1b\[[0-9]+m//g" \
		-e "s/\x1b\[m//g" | \
		${ove_cmd2pathname["grep"]:?} --color=never ': [0-9]\+ new commit' | \
		while IFS=' ' read -r repo n foo bar; do
			repo=${repo/:/}
			if [ "$repo" = "$OVE_OWEL_NAME" ]; then
				repo=".owel"
			fi
			${ove_cmd2pathname["mkdir"]:?} -p ${d}/${repo}
			ove_repo_cmd ${OVE_BASE_DIR}/${repo} format-patch -q -${n} -o ${d}/${repo}
		done

	if [ $(${ove_cmd2pathname["find"]:?} ${d} -type f | ${ove_cmd2pathname["wc"]:?} -l) -eq 0 ]; then
		return 1
	fi

	if [ $# -eq 1 ]; then
		f="$1"
		if [[ "${f}" != *.tar.bz2 ]]; then
			f+=".tar.bz2"
		fi
	else
		f="${PWD}/${OVE_OWEL_NAME}-patches-$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S').tar.bz2"
	fi

	if ! ${ove_cmd2pathname["touch"]:?} "${d}"/${OVE_SHA:?}-format-patch; then
		return 1
	elif ! ${ove_cmd2pathname["tar"]:?} -C "${d}" -cjf "${f}" --owner=0 --group=0 .; then
		ove_echo_error_noprefix "format-patch: tar failed"
		return 1
	fi
	${ove_cmd2pathname["readlink"]:?} -f -- "${f}"
}

# am:file:apply a bz2 archive file created with 'format-patch':CORE
function ove-am {
	ove_entry || return

	local d
	local f
	local r
	local repos
	local ret=0

	if [ $# -ne 1 ] || ! [ -e $1 ]; then
		ove_command_usage
		return 1
	fi

	d="${OVE_OWEL_TMP_DIR}/am"
	f="$1"
	if ! ${ove_cmd2pathname["mkdir"]:?} -p ${d}; then
		return 1
	fi

	# clean up any directories
	${ove_cmd2pathname["find"]:?} ${d} -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} \;

	# sanity check archive
	if ! ${ove_cmd2pathname["tar"]:?} -tf "$f" | ${ove_cmd2pathname["grep"]:?} -q '\.\/[0-9a-f]\+\-format-patch$'; then
		ove_echo_error_noprefix "archive '$f' was not created with 'ove format-patch'"
		return 1
	fi

	# unpack
	if ! ${ove_cmd2pathname["tar"]:?} -C "${d}" --exclude './*-format-patch' -xf "$f" --no-same-owner; then
		return 1
	fi

	repos=$(${ove_cmd2pathname["find"]:?} ${d} -type f -print0 | ${ove_cmd2pathname["xargs"]:?} -0 dirname | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u)
	if [ "${repos}" = "" ]; then
		return 1
	fi

	for r in ${repos}; do
		r=${r/${d}\/}
		if [ "$r" = ".owel" ]; then
			ove_echo_yellow_noprefix "${OVE_OWEL_NAME}"
		else
			ove_echo_yellow_noprefix "${r}"
		fi

		if [ ! -d "${OVE_BASE_DIR}/${r}" ]; then
			ove_echo_error_noprefix "repo '${OVE_BASE_DIR}/${r}' does not exist, try 'ove fetch ${r}'"
			((ret++))
			continue
		fi

		# apply patch(es)
		if ! ove_repo_cmd ${OVE_BASE_DIR}/${r} am ${d}/${r}/*; then
			ove_echo_error_noprefix "git am failed for repo '${r}'. Automatically running 'git am --abort'. Failed patch(es): ${d}/${r}/"
			ove_repo_cmd ${OVE_BASE_DIR}/${r} am --abort
			((ret++))
		fi
	done

	return ${ret}
}

# $1: behind|ahead
function ove_any_repo {
	# shellcheck disable=SC2016
	ove_revtab_forall_parallel '${ove_cmd2pathname["git"]:?} branch -v --format="%(upstream:track,nobracket)" --list $(${ove_cmd2pathname["git"]:?} rev-parse --abbrev-ref HEAD 2> /dev/null)' |
	while read -r line; do
		if [[ ${line} == *$1* ]]; then
			exit 1
		fi
	done

	return $((PIPESTATUS[1] ^= 1))
}

# $1: behind|ahead
function ove_list_repositories {
	# shellcheck disable=SC2016
	ove_revtab_forall 'echo -n ${repo_basename}:; ${ove_cmd2pathname["git"]:?} "rev-parse" "--abbrev-ref" "HEAD" 2> /dev/null' | \
	while IFS=: read -r repo revision; do
		if [ "${revision}" = "HEAD" ]; then
			continue
		elif [[ $(${ove_cmd2pathname["git"]:?} -C $(ove_repo2fullpath "${repo}") "branch" "-v" "--format=%(upstream:track,nobracket)" "--list" "${revision}") == *$1* ]]; then
			echo "${repo}"
		fi
	done
}

# pull:[git...]:git pull for all/specified repositories:CORE
function ove-pull {
	ove_entry || return

	local autostash
	local repo
	local repos

	# turn off monitor mode to get rid of "Done" messages
	set +m

	autostash=0
	if declare -p ove_revtab_git_cmd_opts &>/dev/null && \
		[ "${ove_revtab_git_cmd_opts["*:pull"]}" != "" ] && \
		[[ "${ove_revtab_git_cmd_opts["*:pull"]}" == *--autostash* ]]; then
		autostash=1
	fi

	if [ $# -ge 1 ]; then
		for repo in $(ove_validate_repo_list "${@//${OVE_BASE_DIR}\/}"); do
			if [ ${autostash} -eq 1 ]; then
				true
			elif declare -p ove_revtab_git_cmd_opts &>/dev/null && \
				[ "${ove_revtab_git_cmd_opts["${repo}:pull"]}" != "" ] && \
				[[ "${ove_revtab_git_cmd_opts["${repo}:pull"]}" == *--autostash* ]]; then
				true
			elif ove_repo_is_dirty ${OVE_BASE_DIR}/${repo}; then
				ove_echo_error_noprefix "cannot pull '${repo}' as it is dirty"
				continue
			fi
			repos+="${repo} "
		done
	else
		if ove_any_repo behind; then
			for repo in $(ove_list_repositories "behind"); do
				if [ ${autostash} -eq 1 ]; then
					true
				elif declare -p ove_revtab_git_cmd_opts &>/dev/null && \
					[ "${ove_revtab_git_cmd_opts["${repo}:pull"]}" != "" ] && \
					[[ "${ove_revtab_git_cmd_opts["${repo}:pull"]}" == *--autostash* ]]; then
					true
				elif ove_repo_is_dirty ${OVE_BASE_DIR}/${repo}; then
					ove_echo_error_noprefix "cannot pull '${repo}' as it is dirty"
					continue
				fi

				repos+="${repo} "
			done
		else
			repos=${OVE_REPO_LIST//${OVE_BASE_DIR}\/}
		fi
	fi

	for repo in ${repos}; do
		ove_revtab_pull_one ${repo} | ${ove_cmd2pathname["grep"]:?} -v '^\['
		if [ ${PIPESTATUS[0]} -ne 0 ]; then
			return 1
		fi

		if [ "${repo##*/}" = "${OVE_OWEL_NAME}" ]; then
			# validate revtab revision
			ove_revtab_check

			# patch repos
			ove_patch_repos || true
		fi
	done

	if [ "${repos}" != "" ]; then
		ove_revtab_status ${repos} | ${ove_cmd2pathname["grep"]:?} -v '^\['
	fi

	# turn on monitor mode
	set -m
}

# apply-cached:patch:apply one OVE patch to index:CORE
function ove-apply-cached {
	OVE_APPLY_CACHED=1 ove-apply "$@"
}

# apply:patch:apply one OVE patch:CORE
function ove-apply {
	ove_entry || return

	local args
	local lineno
	local p
	local patches
	local q
	local repo_basename
	local repo_fullpath
	local ret=0

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	elif ! ove_check_command "csplit"; then
		return 1
	elif ! [ -e "$1" ]; then
		ove_echo_error_noprefix "'$1' patch file not found"
		return 1
	elif ! [ -s "$1" ]; then
		ove_echo_error_noprefix "'$1' is empty"
		return 1
	fi

	${ove_cmd2pathname["cp"]:?} -a "$1" "${OVE_OWEL_TMP_DIR}"
	p="${OVE_OWEL_TMP_DIR}/${1##*/}"

	# get a list of line numbers where to split the file
	lineno=$(${ove_cmd2pathname["grep"]:?} -n "${OVE_COLOR_YELLOW_X}" "${p}"| ${ove_cmd2pathname["tail"]:?} -n +2 | ${ove_cmd2pathname["cut"]:?} -d: -f1 | ${ove_cmd2pathname["xargs"]:?})

	# remove color codes
	${ove_cmd2pathname["sed"]:?} -i \
		-r \
		-e "s/\x1b\[[0-1];3[0-9];7m//g" \
		-e "s/\x1b\[[0-9]+m//g" \
		-e "s/\x1b\[m//g" ${p}

	if ! ${ove_cmd2pathname["file"]:?} "${p}" | ${ove_cmd2pathname["grep"]:?} -q "unified diff"; then
		ove_echo_error_noprefix "'${p}' is not a unified diff"
		return 1
	fi

	# remove any old patch file(s)
	${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR} -maxdepth 1 -name 'ove-apply-patch*' -exec rm {} \;

	if [ "${lineno}" = "" ]; then
		patches=${p}
	else
		# one patch per git
		if ! ${ove_cmd2pathname["csplit"]:?} -s -z --prefix ${OVE_OWEL_TMP_DIR}/ove-apply-patch ${p} ${lineno}; then
			ove_echo_error_noprefix "ops, csplit failed"
			return 1
		fi

		patches=$(${ove_cmd2pathname["find"]:?} ${OVE_OWEL_TMP_DIR} -maxdepth 1 -name 'ove-apply-patch*' | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	fi

	if [ "${OVE_APPLY_CACHED}" = "1" ]; then
		args="--index"
	fi

	for p in ${patches}; do
		repo_basename=$(${ove_cmd2pathname["head"]:?} -1 -q ${p})
		repo_basename=${repo_basename/${OVE_BASE_DIR}\/}
		repo_fullpath=$(ove_repo2fullpath ${repo_basename})
		if [ "${repo_fullpath}" = "" ] || [ ! -d "${repo_fullpath}" ]; then
			ove_echo_yellow_noprefix "'${repo_basename}': unknown repo, next..."
			continue
		fi

		# rename the patch
		q="${OVE_OWEL_TMP_DIR}/ove-apply-${repo_basename////-}.patch"
		${ove_cmd2pathname["mv"]:?} ${p} ${q}
		if ove_dir_is_repo "${repo_fullpath}"; then
			# Run 'git apply --check' and if ok, apply the patch
			if ! ove_repo_cmd "${repo_fullpath}" apply ${args} --check ${q} 2> /dev/null; then
				ove_echo_yellow_noprefix "${repo_basename}: patch '${q}' does not apply"
				((ret++))
				continue
			fi

			# apply the patch
			ove_repo_cmd "${repo_fullpath}" apply ${args} ${q}
		fi
	done

	return ${ret}
}

# $1: repo
# $2: patch file
function ove_patch_one_repo {
	local p
	local repo
	local repo_s
	local ret=0
	local repo_shortpath

	repo="$1"
	p="$2"
	repo_s="$(ove_repo2shortpath ${repo})"

	if [ ! -d "${repo}" ]; then
		return 0
	elif ove_repo_cmd ${repo} apply -R --check "${p}" 2> /dev/null; then
		return 0
	elif ove_repo_cmd ${repo} apply --check "${p}" 2> /dev/null; then
		printf "%-${OVE_REPO_LIST_WIDTH}sApplying patch '%s'\n" ${repo_s} ${p}
		if [ "${OVE_PATCH_REPOS_METHOD:?}" = "apply" ]; then
			if ! ove_repo_cmd ${repo} apply "${p}" 2> /dev/null; then
				ret=1
			fi
		elif [ "${OVE_PATCH_REPOS_METHOD:?}" = "am" ] || [ "${OVE_PATCH_REPOS_METHOD:?}" = "auto" ]; then
			if ! ove_repo_cmd ${repo} am "${p}" 2> /dev/null; then
				if [ "${OVE_PATCH_REPOS_METHOD:?}" = "am" ]; then
					ret=1
				elif ! ove_repo_cmd ${repo} apply "${p}" 2> /dev/null; then
					ret=1
				fi
			fi
		else
			ove_echo_error_noprefix "unknown patch method: ${OVE_PATCH_REPOS_METHOD}"
			ret=1
		fi
	else
		ret=1
	fi

	return ${ret}
}

# $1: repos [optional]
function ove_patch_repos {
	local find_opts
	local find_search_dirs
	local n=${FUNCNAME^^}
	local p
	local repo
	local repos
	local ret=0

	if  [ ! -d ${OVE_OWEL_DIR}/patches ]; then
		return
	elif [ -n "${!n}" ] && [ "${!n}" -eq 0 ]; then
		return
	fi

	if [ $# -eq 0 ]; then
		find_search_dirs="${OVE_OWEL_DIR}/patches/"
	else
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			return 1
		fi

		for repo in ${repos}; do
			if [ ! -d "${OVE_OWEL_DIR}/patches/${repo}" ]; then
				continue
			fi
			find_opts="-maxdepth 1"
			find_search_dirs+="${OVE_OWEL_DIR}/patches/${repo} "
		done
		if [ "${find_search_dirs}" = "" ]; then
			return 1
		fi
	fi

	if [ "${OVE_PATCH_REPOS_METHOD:?}" = "am" ] && ! ove_git_config_check; then
		ove_echo_warning_noprefix "not possible to patch repo(s) using 'git am' as git config user.email/user.name is not set"
		return 1
	fi

	while read -r p; do
		repo="${p/${OVE_OWEL_DIR}\/patches\/}"
		repo="${repo%/*}"
		repo="${OVE_BASE_DIR}/${repo}"

		if ! ove_patch_one_repo "${repo}" "${p}"; then
			((ret++))
		fi
	done < <(${ove_cmd2pathname["find"]:?} ${find_search_dirs} ${find_opts} -name "*.patch" -or -name "*.diff" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})

	return ${ret}
}

# patch-repo:[git...]:patch all/specified repositories with $OVE_OWEL_DIR/patches/[<git>/]{*.diff,*.patch} (override OVE_PATCH_REPOS):CORE
function ove-patch-repo {
	ove_entry || return

	OVE_PATCH_REPOS=1 ove_patch_repos "$@"
}

# $1: url
function ove_get_git_protocol {
	if [[ "$1" = ssh://* ]]; then
		echo "ssh://"
	elif [[ "$1" = git://* ]]; then
		echo "git://"
	elif [[ "$1" = http* ]]; then
		re="^http[s]{0,1}://"
		if [[ "${1}" =~ ${re} ]]; then
			echo "${BASH_REMATCH[0]}"
		fi
	elif [[ "$1" = ftp* ]]; then
		re="^ftp[s]{0,1}://"
		if [[ "${1}" =~ ${re} ]]; then
			echo "${BASH_REMATCH[0]}"
		fi
	else
		return 1
	fi
}

# append revtab with submodules
function ove_submodule2revtab {
	local path
	local protocol
	local repo
	local repos_with_submodules
	local sha
	local submodule
	local url
	local url_super

	if [ $# -eq 0 ]; then
		return
	fi

	for repo in "$@"; do
		if [ -s ${repo}/.gitmodules ]; then
			repos_with_submodules+="${repo} "
		fi
	done

	if [ "${repos_with_submodules}" = "" ]; then
		return
	fi

	for repo in ${repos_with_submodules}; do
		for submodule in $(ove_repo_cmd ${repo} config --file .gitmodules --list | ${ove_cmd2pathname["cut"]:?} -d'.' -f2 | ${ove_cmd2pathname["sort"]} -u); do
			# get path
			path=$(ove_repo_cmd ${repo} config --file .gitmodules --get "submodule.${submodule}.path")
			if [ "${path}" = "" ]; then
				ove_echo_warning_noprefix "import-submodules: could not get path for submodule '${submodule}'"
				continue
			fi

			# already imported?
			if [[ -v ove_revtab_name2index[${repo//${OVE_BASE_DIR}\/}/${path}] ]]; then
				continue
			fi

			# get url
			url=$(ove_repo_cmd ${repo} config --file .gitmodules --get "submodule.${submodule}.url")
			if [ "${url}" = "" ]; then
				ove_echo_warning_noprefix "import-submodules: could not get url for submodule '${submodule}'"
				continue
			fi

			# relative to superproject?
			if [[ "$url" = ./* ]] || [[ "$url" = ../* ]]; then
				url_super=$(ove_get_fetch_url $repo origin)
				if [ "$url_super" = "noremote" ]; then
					continue
				elif ! protocol=$(ove_get_git_protocol "$url_super"); then
					url=$(cd /tmp || exit; ${ove_cmd2pathname["readlink"]:?} -m ${url_super}/${url})
					url=${url/\/tmp\/}
				else
					url=$(cd /tmp || exit; ${ove_cmd2pathname["readlink"]:?} -m $PWD/${url_super/$protocol}/${url})
					url=${url/\/tmp\/}
					url="${protocol}${url}"
				fi
			fi

			# shellcheck disable=SC2016
			sha=$(ove_repo_cmd ${repo} submodule | \
				${ove_cmd2pathname["grep"]:?} " ${path}$" | \
				${ove_cmd2pathname["awk"]:?} '{print $1}')
			sha=${sha/+/}
			sha=${sha/-/}
			if [ "${sha}" = "" ]; then
				ove_echo_warning_noprefix "import-submodules: could not get SHA-1 for submodule '${submodule}'"
				continue
			fi

			echo "${repo//${OVE_BASE_DIR}\/}/${path} ${url} ${url} ${sha}"
		done
	done | ${ove_cmd2pathname["tee"]:?} -a ${OVE_OWEL_DIR}/revtab

	return
}

# import-submodules:[git]:append submodule(s) to 'revtab' and run fetch for all/specified git repositories:CORE
function ove-import-submodules {
	ove_entry || return
	ove_revtab_sanity || return

	local imports
	local out
	local repos

	while true; do
		if [ $# -ge 1 ]; then
			repos=$(ove_validate_repo_list "$@")
		else
			repos=${OVE_REPO_LIST}
		fi

		if [ "${repos}" = "" ]; then
			return
		fi
		out=$(ove_submodule2revtab ${repos})
		# shellcheck disable=SC2016
		imports=$(printf "%s\n" "${out}" | ${ove_cmd2pathname["awk"]:?} '{print $1}')
		if [ "$imports" = "" ]; then
			break
		elif ! ove_reinit; then
			return 1
		elif ! ove-fetch $imports; then
			ove_echo_warning_noprefix "'ove fetch $(printf "%s " $imports)' failed"
		fi
	done

	return 0
}

# do:dir command:run a command within 'dir' relative to ${OVE_BASE_DIR}:CORE
function ove-do {
	ove_entry || return

	local cmd
	local dir

	dir=${1/${OVE_BASE_DIR}}
	cmd="${*:2}"

	if ! [ -d "${OVE_BASE_DIR}/${dir}" ]; then
		ove_echo_error_noprefix "'${OVE_BASE_DIR}/${dir}' is not a directory"
		return 1
	elif ! cd ${OVE_BASE_DIR}/${dir} 2> /dev/null; then
		ove_echo_error_noprefix "'cd ${OVE_BASE_DIR}/${dir}' failed"
		return 1
	fi

	eval "${cmd}"
}

# fetch-fetched: :fetch already fetched repositories, ends with ove status:CORE
function ove-fetch-fetched {
	ove_entry || return

	# shellcheck disable=SC2016
	ove-fetch $(ove-status | ${ove_cmd2pathname["awk"]:?} '{print $1}')
}

# fetch-remains: :fetch not yet fetched repositories, ends with ove status:CORE
function ove-fetch-remains {
	ove_entry || return

	local a
	local n

	mapfile -t -d ' ' a <<< "${OVE_REPO_LIST}"
	if [ ${OVE_REPOS_FETCHED} -eq "${#a[@]}" ]; then
		return 0
	fi

	# save repos fetched
	ove-forall "pwd" | \
		${ove_cmd2pathname["sed"]:?} -e "s,${OVE_BASE_DIR}/,,g" | \
		LC_ALL=C ${ove_cmd2pathname["sort"]:?} \
		> "${OVE_TMP}"/a

	# save all repos
	printf "%s\n" ${OVE_REPO_LIST//${OVE_BASE_DIR}\/} | \
		LC_ALL=C ${ove_cmd2pathname["sort"]:?} \
		> "${OVE_TMP}"/b

	# compare and save the remains
	LC_ALL=C ${ove_cmd2pathname["comm"]:?} \
		-1 \
		-3 \
		"${OVE_TMP}"/a \
		"${OVE_TMP}"/b \
		> "${OVE_TMP}"/c

	n=$(${ove_cmd2pathname["wc"]:?} -l < "${OVE_TMP}"/c)
	if [ "$n" -gt 0 ]; then
		# fetch remains
		ove-fetch $(cat "${OVE_TMP}"/c)
	fi
	${ove_cmd2pathname["rm"]:?} "${OVE_TMP}"/{a,b,c}
}

# fetch:[git...]:fetch all/specified repositories, ends with ove status:CORE
function ove-fetch {
	ove_entry || return

	local repos

	if [ $# -ne 0 ]; then
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			return 1
		fi
	fi

	if ! ove_revtab_fetch ${repos}; then
		return $?
	fi

	ove-status ${repos}
}

# tag: :list git tags within ${OVE_OWEL_DIR}:CORE
function ove-tag {
	ove_entry || return

	ove_repo_cmd "${OVE_OWEL_DIR}" log --tags --simplify-by-decoration --pretty="format:%ai %D"
}

# log: :project commit log for branch '${OVE_OWEL_CI_BRANCH}':CORE
function ove-log {
	ove_entry || return

	local b

	if ove_repo_cmd "${OVE_OWEL_DIR}" branch -r | ${ove_cmd2pathname["grep"]:?} -q ${OVE_OWEL_CI_BRANCH}; then
		b="${OVE_OWEL_CI_BRANCH}"
	fi

	ove_repo_cmd "${OVE_OWEL_DIR}" log --decorate ${b}
}

# checkout:[rev[ [purge|autostash]]]:git checkout for all git repositories or checkout a new project revision, USE 'purge' WITH CARE:CORE
function ove-checkout {
	ove_entry || return

	local cmd
	declare -a dirty_repos
	local m
	local proj
	local repo
	local revision

	revision="$1"

	if [ $# -eq 0 ]; then
		mapfile -t dirty_repos < <(ove_list_dirty_repos)

		# shellcheck disable=SC2016
		cmd='ove_repo_cmd ${repo} diff --quiet || (ove_echo_yellow_noprefix ${repo_basename}; ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} checkout)'
		(ove_revtab_forsome "${cmd}" "${dirty_repos[@]}")

		if [[ "${dirty_repos[*]}" =~ ${OVE_OWEL_NAME} ]]; then
			ove_reinit
		fi
	elif [ $# -eq 1 ] || [ $# -eq 2 ]; then
		if [ "$2" = "purge" ]; then
			# shellcheck disable=SC2016
			cmd='ove_repo_cmd ${repo} reset; ove_repo_cmd ${repo} checkout .'

			read -p "proceed to run 'git reset && git checkout .' for all git repositories? (y/N) " -r
			echo
			if [[ ${REPLY} =~ ^[Yy]$ ]]; then
				read -p "are you really sure? (y/N) " -r
				echo
				if [[ ${REPLY} =~ ^[Yy]$ ]]; then
					ove_revtab_forall "${cmd}"
				fi
			fi
		elif [ "$2" = "autostash" ]; then
			mapfile -t dirty_repos < <(ove_list_dirty_repos)

			for repo in "${dirty_repos[@]}"; do
				ove_repo_cmd "${repo}" stash save -q "stashed by ove-checkout"
			done
		else
			mapfile -t dirty_repos < <(ove_list_dirty_repos)

			if [ "${#dirty_repos[@]}" -ne 0 ]; then
				ove_echo_error_noprefix "you have staged/unstaged changes in the following repositories:"
				ove-status "${dirty_repos[@]}"
				return 1
			fi
		fi

		if [ ${OVE_REVTAB_CHECK} -eq 0 ]; then
			ove_echo_warning_noprefix "revtab check (=OVE_REVTAB_CHECK) is DISABLED for this workspace"
			ove_echo_warning_noprefix "all repos (except '${OVE_OWEL_NAME}') will stay on their current revisions"
			echo
		fi

		ove_repo_cmd "${OVE_OWEL_DIR}" fetch

		m=${OVE_REPO_LIST_WIDTH}
		ove_repo_cmd "${OVE_OWEL_DIR}" "-c advice.detachedHead=false checkout" "${revision}" |& \
			${ove_cmd2pathname["sed"]:?} -e "1s|^|$(ove_echo_yellow_noprefix ${OVE_OWEL_NAME})$(printf "%0.s " $(eval echo "{1..$((m - ${#OVE_OWEL_NAME}))}"))|g" \
			-e "2s|^|$(printf "%0.s " $(eval echo "{1..$((m))}"))|g"
		if [ ${PIPESTATUS[0]} -ne 0 ]; then
			# cleanup
			if [ "$2" = "autostash" ]; then
				for repo in "${dirty_repos[@]}"; do
					ove_repo_cmd "${OVE_BASE_DIR}/${repo}" stash pop -q
				done
			fi

			return 1
		fi

		echo ---

		# init everything
		ove_init

		# clone and checkout
		ove_revtab_clone_and_checkout

		# validate revtab revision
		ove_revtab_check

		if [ "$2" = "autostash" ]; then
			for repo in "${dirty_repos[@]}"; do
				ove_repo_cmd "${OVE_BASE_DIR}/${repo}" stash pop -q
			done
		fi

		# patch all repos
		ove_patch_repos || true
	fi

	return 0
}

# checkout-by-date:date:checkout by date (ignore revtab):CORE
function ove-checkout-by-date {
	ove_entry || return

	local d
	local prev
	local rev

	if [ $# -ne 1 ]; then
		ove_command_usage
		return 1
	elif ! d=$(${ove_cmd2pathname["date"]:?} -d"$1" "+%Y-%m-%d %H:%M"); then
		return 1
	elif ! rev=$(ove_get_revision "$OVE_OWEL_DIR"); then
		return 1
	elif [ "${OVE_REVTAB_CHECK}" -eq 1 ]; then
		ove_echo_error_noprefix "disable revtab-check with 'ove revtab-check 0' and try again"
		return 1
	elif ! ${ove_cmd2pathname["git"]:?} -C "$OVE_OWEL_DIR" show-ref -q --heads "${rev}"; then
		ove_echo_error_noprefix "OWEL '$OVE_OWEL_DIR' is not on a branch"
		return 1
	elif ! prev="$(${ove_cmd2pathname["git"]:?} -C "${OVE_OWEL_DIR}" rev-list -n 1 --first-parent --before="${d}" "${rev}")"; then
		return 1
	elif [ "${prev}" = "" ]; then
		return 1
	elif ! ove-checkout "${prev}"; then
		return 1
	elif ! ove-revtab-sync; then
		return 1
	fi

	# shellcheck disable=SC2016
	ove-forall '
		if [ ${repo} != ${OVE_OWEL_DIR} ] && [ ${repo} != ${OVE_DIR} ]; then
			rev=$(ove_get_revision ${repo})
			if ${ove_cmd2pathname["git"]:?} show-ref -q --heads ${rev}; then
				${ove_cmd2pathname["git"]:?} checkout -q $(git rev-list -n 1 --first-parent --before="'$d'" ${rev})
			fi
		fi'
}

# list-commands:[pattern]:list commands:CORE
function ove-list-commands {
	ove_entry || return

	local _help
	local a
	local b
	local c
	local r
	local s

	if [ $# -eq 1 ] && [ "$1" = "PLUGIN" ]; then
		{
			echo "cmd:args:help:repo"
			echo "---"
			for a in $(ove-list-scripts); do
				s=${a##*/}
				_help=$(set | \
					${ove_cmd2pathname["grep"]:?} ove_plugin_helptext=\"$s: | \
					${ove_cmd2pathname["grep"]:?} -v '\$'| \
					${ove_cmd2pathname["cut"]:?} -d'"' -f2 | \
					${ove_cmd2pathname["sed"]:?} -e 's,PLUGIN$,,g')

				if [[ "$a" == $OVE_OWEL_DIR* ]]; then
					echo "$_help:$OVE_OWEL_NAME"
					continue
				elif [[ "$a" == $OVE_DIR* ]]; then
					echo "$_help:OVE"
					continue
				fi
				r=${a//${OVE_BASE_DIR}\/}
				r=${r/\/.ove*}
				echo "$_help:$r"
			done
		} | ${ove_cmd2pathname["column"]:?} -t -s':'
		return 0
	fi

	a=$(${ove_cmd2pathname["grep"]:?} -B1 "^function ove-" "${OVE_BASE_DIR}"/ove | \
		${ove_cmd2pathname["grep"]:?} '#' | \
		${ove_cmd2pathname["cut"]:?} -b3-| \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	b=$(set | \
		${ove_cmd2pathname["grep"]:?} helptext | \
		${ove_cmd2pathname["grep"]:?} -v '\$'| \
		${ove_cmd2pathname["cut"]:?} -d'"' -f2)

	c=$(printf "${a}\n${b}")

	{
		echo "cmd:args:help:category"
		{
			echo "---"
			if [ $# -eq 1 ]; then
				printf "${c}\n" | ${ove_cmd2pathname["grep"]:?} "$1"
			else
				printf "${c}\n"
			fi
		} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?};
	} | ${ove_cmd2pathname["column"]:?} -t -s:
}

# help:[pattern]:OVE help:CORE
function ove-help {
	ove_entry || return

	if [ $# -eq 0 ]; then
		ove_help
	else
		ove_help | ${ove_cmd2pathname["grep"]:?} -E --color=always "${1}"
	fi
}

function ove_list_command_categories {
	# shellcheck disable=SC2016
	ove-list-commands | \
		${ove_cmd2pathname["awk"]:?} '{print $NF}' | \
		${ove_cmd2pathname["sort"]:?} -u | \
		${ove_cmd2pathname["grep"]:?} '[A-Z]'
}

# list-commands-by-category: :list commands grouped by category:CORE
function ove-list-commands-by-category {
	local c

	for c in $(ove_list_command_categories); do
		if [ "$c" = "PLUGIN" ]; then
			continue
		fi
		ove-list-commands | ${ove_cmd2pathname["grep"]:?} -E "$c|^cmd|^---"
		echo
		echo
		echo
	done

	ove_echo_cyan_noprefix "PLUGIN"
	ove-list-commands PLUGIN
}

function ove_help {
	local f
	local h

	ove_echo_cyan_noprefix "commands"
	echo
	ove-list-commands
	echo
	${ove_cmd2pathname["cat"]:?} <<EOF

$(ove_echo_cyan_noprefix "high level git commands")

# status of all git repositories
ove status

# synchronize with the outside world
ove fetch

# view local changes in all repos
ove diff

# interactively ask what hunk to checkout
ove checkout

# checkout a specific revision
ove checkout 1.0.2

# search for the string 'deadbeef'
ove grep deadbeef

# create a archive of all 'ahead'-commits
ove format-patch featY.tar.bz2

# apply an archive that someone sent me
ove am featY.tar.bz2

$(ove_echo_cyan_noprefix "build related commands")

# list build order
ove build-order

# initial build for all projects, runs 'bootstrap, configure, build, install'
ove buildme
ove buildme-parallel

# first build for a specific project 'projX', runs 'bootstrap, configure, build, install' for projX and all deps
ove buildme projX
ove buildme-parallel projX

# build projects in order, runs '[clean], build, install' for all projects
ove make

# build a specific project and all project dependencies, runs '[clean], build, install' for projX and deps
ove make projX

# build a specific project without dependencies, runs 'build, install' for projX
ove make projX-nodeps

# clean projects
ove clean

# remove all untracked files for all git repositories USE WITH CARE
ove mrproper

$(ove_echo_cyan_noprefix "utility commands")

# list patches your friends have upstreamed since your last pull
ove news

# show new patches
ove show-news # (or show-behind)

# run 'ls -l' for all repos
ove forall ls -l

# run 'git maintenance run --quiet' for all repos (in parallel)
ove forall-parallel git maintenance run --quiet

# open your modified files in vi/emacs
ove vi
ove emacs

# open modified files in vi, but only files with 'test' in the name
ove vi test

# search all repositories for 'au' using The Silver Searcher
ove ag au

# search all repositories using fzf and vi
ove gfv "int i = 0"

# trigger a build of projX when a file is modified
ove clean projX && ove loop 0 1 0 build projX
# now modify a file within projX in another tmux pane/terminal

# open a few tmux panes that runs the following OVE commands: news, ahead, fetch
ove ide

$(ove_echo_cyan_noprefix "log commands")

# run one command
ove fetch

# check the output of the last command in less
ove l

# re-run the last command with proper timing
ove lr

# re-run the last command at 10x speed
ove lr 10

# re-run all commands from yesterday at 10x speed
ove lastlog-replay $(date -d @$(($(date +"%s")-86400)) +"%Y%m%d")- 10

# run htop for 5 seconds, replay the command immediately after
ove do . timeout --foreground 5 htop -d 0.1 || ove lr

$(ove_echo_cyan_noprefix "distrocheck")

# steps:
#   ove        use the OVE workspace (map it or by running the oneliner) within the container
#   running    leave the container running
#   ssh        install sshd within the container and use ssh instead of 'incus|lxc exec'
#   ssh_config update \$HOME/.ssh/config with host entries
#   stopped    leave the container in stopped state
#   user       run jobs as user
#   verbose    debug printouts
#   worktree   run distcheck within an OVE worktree
#   X          Xpra+Xfce
#
# run 'ove distcheck foo' within a Ubuntu 24.04 container, run the job as user, delete the container when done
export OVE_DISTROCHECK_STEPS="user ove"
ove distrocheck foo ubuntu/24.04/amd64

# run a local script "test.sh" within Ubuntu 24.04, enable debug prints, leave the container running
echo "set -x;date;whoami;hostname;ip addr" > test.sh
export OVE_DISTROCHECK_STEPS="running verbose"
ove distrocheck test.sh ubuntu/24.04/amd64

# (tmux only) run 'ove distcheck ag' within three Linux distributions at the same time, run the job as root, leave the containers running
export OVE_DISTROCHECK_STEPS="ove running"
ove distrocheck-parallel ag alpine/edge/amd64 fedora/40/amd64 ubuntu/24.04/amd64

# install Xpra
bash \${OVE_DIR:?}/hooks/xpra/pre-distrocheck

# install incus
bash \${OVE_DIR:?}/hooks/incus/pre-distrocheck

# attach to a Xfce desktop running within an Alpine 3.20 container 'alice', enable debug prints, leave the container running
export OVE_DISTROCHECK_CONTAINER_NAME="alice"
export OVE_DISTROCHECK_STEPS="running verbose X"
export OVE_DISTROCHECK_XPRA_CLIENT_ARGS="attach"
ove distrocheck true alpine/3.20/amd64
# re-attach
xpra attach --ssh=ssh ssh:alice

$(ove_echo_cyan_noprefix "replicate")

# replicate OVE workspace to a tmp directory on localhost
ove replicate localhost

# replicate OVE workspace to a specific directory on remotehost (ssh)
ove replicate remotehost /var/tmp/backup

# keep replicated workspace in sync with OVE workspace. Save any changes in the replicated workspace though "ove stash" and/or "ove format-patch".
ove replicate host /var/tmp/backup save

# keep replicated workspace in sync (forced) with OVE workspace. USE WITH CARE!
ove replicate host /var/tmp/backup force

$(ove_echo_cyan_noprefix "configuration")

# OVE tries to keep all repos in-sync with whatever is stated in the '\${OVE_OWEL_DIR}/revtab' file.
# If you don't want this behaviour set the 'OVE_REVTAB_CHECK' config to '0'. Choose one of:
ove add-config \${OVE_OWEL_DIR}/.oveconfig OVE_REVTAB_CHECK 0
ove add-config \${OVE_OWEL_STATE_DIR}/.oveconfig OVE_REVTAB_CHECK 0
ove add-config \${OVE_GLOBAL_STATE_DIR}/.oveconfig OVE_REVTAB_CHECK 0
ove add-config \${HOME}/.oveconfig OVE_REVTAB_CHECK 0

# NOTE: OVE config files are read in this order:
\${OVE_OWEL_DIR}/.oveconfig -> \${OVE_OWEL_STATE_DIR}/.oveconfig -> \${OVE_GLOBAL_STATE_DIR}/.oveconfig -> \${HOME}/.oveconfig
# I.e. '\${HOME}/.oveconfig' has the highest precedence.
EOF

	f=$(ove_revtab_list_fullpath)
	f="${f// /\/.ove/help }/.ove/help"

	# project and repo specific help
	for h in "${OVE_OWEL_DIR}/help" ${f}; do
		if [ ! -s "${h}" ]; then
			continue
		fi
		echo
		if [ -x "${h}" ]; then
			source "${h}"
		else
			${ove_cmd2pathname["cat"]:?} "${h}"
		fi
	done

	return 0
}

# rg:pattern:search OVE workspace using rg [duckduckgo.com/?q=ripgrep]:SEARCH
function ove-rg {
	ove_entry || return

	local cmd

	if ! ove_check_command "rg"; then
		return 1
	fi

	if [ $# -ne 1 ]; then
		if [ $# -eq 0 ]; then
			echo "error: no pattern" 1>&2
		fi
		ove_command_usage
		return 1
	fi

	cmd="${ove_cmd2pathname["rg"]:?} --no-ignore --hidden -S -n --color=always $* -- | "
	# shellcheck disable=SC2016
	cmd+='${ove_cmd2pathname["sed"]:?} -e "s,^,${PWD}/,g"'
	if ! (cd $OVE_BASE_DIR || exit; eval $cmd; ); then
		return 1
	fi
}

# ag:pattern:search OVE workspace using ag [duckduckgo.com/?q=The+Silver+Searcher]:SEARCH
function ove-ag {
	ove_entry || return

	local cmd

	if ! ove_check_command "ag"; then
		return 1
	fi

	if [ $# -ne 1 ]; then
		if [ $# -eq 0 ]; then
			echo "error: no pattern" 1>&2
		fi
		ove_command_usage
		return 1
	fi

	cmd="${ove_cmd2pathname["ag"]:?} --hidden -U --color '$*' -- | "
	# shellcheck disable=SC2016
	cmd+='${ove_cmd2pathname["sed"]:?} -e "s,^,${PWD}/,g"'
	if ! (cd $OVE_BASE_DIR || exit; eval $cmd; ); then
		return 1
	fi
}

# grep:[options] pattern:git grep [options] for all git repositories:SEARCH
function ove-grep {
	ove_entry || return

	if [ $# -eq 0 ]; then
		echo "error: no pattern" 1>&2
		ove_command_usage
		return 1
	fi

	ALLOW_OVERRIDE=1 ove_git_cmd_forall_parallel 0 "grep" "$@"
}

function ove_gf_helper {
	if ! ove_check_command "fzf"; then
		echo "duckduckgo.com/?q=fzf"
		return 1
	elif [ $# -ne 1 ]; then
		echo "error: no pattern" 1>&2
		return 1
	fi

	ove_git_cmd_forall_parallel 0 "grep -i -I -n --color=never" "$@"  | \
		${ove_cmd2pathname["sed"]:?} -e "s,^\([^:]*\):\([0-9]\+\):,\1 +\2 ,"
}

# gfv:pattern:git grep+fzf+vi combo:SEARCH
function ove-gfv {
	ove_entry || return

	local out

	if ! ove_check_command "vi"; then
		return 1
	fi

	if ! out=$(ove_gf_helper "$@"); then
		ove_command_usage
		return 1
	elif [ "${out}" = "" ]; then
		return 1
	fi

	printf "%s\n" "${out}" | \
		SHELL=${ove_cmd2pathname["bash"]:?} \
		${ove_cmd2pathname["fzf"]:?} --bind "enter:execute(< /dev/tty eval \$(echo vi {} | ${ove_cmd2pathname["cut"]:?} -d' ' -f1-3))" \
		--bind "left-click:execute(< /dev/tty eval \$(echo vi {} | ${ove_cmd2pathname["cut"]:?} -d' ' -f1-3))"
}

# gfe:pattern:git grep+fzf+emacs combo:SEARCH
function ove-gfe {
	ove_entry || return

	local out

	if ! ove_check_command "emacs"; then
		return 1
	fi

	if ! out=$(ove_gf_helper "$@"); then
		ove_command_usage
		return 1
	elif [ "${out}" = "" ]; then
		return 1
	fi

	# shellcheck disable=SC2016
	printf "%s\n" "${out}" | \
		SHELL=${ove_cmd2pathname["bash"]:?} \
		${ove_cmd2pathname["fzf"]:?} --bind "enter:execute(eval \$(echo emacs {} | ${ove_cmd2pathname["awk"]:?} '{print \$1,\$3,\$2}'))" \
		--bind "left-click:execute(eval \$(echo emacs {} | ${ove_cmd2pathname["awk"]:?} '{print \$1,\$3,\$2}'))"
}

# blame-history:pattern:git log -G -p pattern for all git repositories:SEARCH
function ove-blame-history {
	ove_entry || return

	if [ $# -eq 0 ]; then
		echo "error: no pattern" 1>&2
		ove_command_usage
		return 1
	fi
	# shellcheck disable=SC2016
	ove_revtab_forall 'ove_echo_yellow_noprefix ${repo_basename}; ove_repo_cmd ${repo} "--no-pager log" --color=always -p -G "'"$*"'"'
}

# blame:pattern:git grep+blame+log combo:SEARCH
function ove-blame {
	ove_entry || return

	local f
	local i
	local line
	local repo
	local res
	local s
	local sha
	local str

	if [ $# -eq 0 ]; then
		ove_echo_error_noprefix "no pattern, try again"
		return 1
	fi

	s="$*"

	for repo in ${OVE_REPO_LIST}; do
		if ! ove_dir_is_repo "${repo}"; then
			continue
		fi

		mapfile -t res < <(ove_repo_cmd "${repo}" "--no-pager grep" --no-color -I -n "${s}" | ${ove_cmd2pathname["cut"]:?} -d: -f1,2)

		for i in "${res[@]}"; do
			f=$(${ove_cmd2pathname["cut"]:?} -d: -f1 <<<"${i}")
			line=$(${ove_cmd2pathname["cut"]:?} -d: -f2 <<<"${i}")
			sha=$(ove_repo_cmd "${repo}" "--no-pager blame" -L"${line}","${line}" "${f}" | ${ove_cmd2pathname["cut"]:?} -d' ' -f1)
			str="${repo}/${f}:${line}"
			if [ "${sha}" = "00000000" ]; then
				str+=" [ Not Committed Yet ]"
			fi
			if [ "${sha}" != "00000000" ]; then
				ove_repo_cmd "${repo}" "--no-pager log" --color=always -1 "${sha}"
			fi
			echo
			${ove_cmd2pathname["head"]:?} -"${line}" "${repo}"/"${f}" | \
				${ove_cmd2pathname["tail"]:?} -1 | \
				${ove_cmd2pathname["grep"]:?} --color=always "${s}" | \
				${ove_cmd2pathname["sed"]:?} -e 's/^/    /g'
			echo
			echo "    File: ${str}"
			echo
		done
	done
}

# $1: file
# $2: config
# $3: value
function ove_config_one {
	local cfg=$1
	local var

	shift
	if [ $# -eq 0 ]; then
		${ove_cmd2pathname["grep"]:?} ${grep_prefix} -E -v '^#|^$' ${cfg} | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
			${ove_cmd2pathname["grep"]:?} -E --color=always "${grep_postfix}"
	elif [ $# -eq 1 ]; then
		if ${ove_cmd2pathname["grep"]:?} -q -i $1 ${cfg}; then
			${ove_cmd2pathname["grep"]:?} ${grep_prefix} -E -v '^#|^$' ${cfg} | \
			${ove_cmd2pathname["grep"]:?} -i $1 | \
			${ove_cmd2pathname["grep"]:?} -E --color=always "${grep_postfix}"
		fi
	elif [ $# -gt 1 ]; then
		var=$1
		if ${ove_cmd2pathname["grep"]:?} -q -w ${var} ${cfg}; then
			${ove_cmd2pathname["sed"]:?} -E -e "s|(^${var}[[:space:]]+).*|\1${*:2}|g" \
				-e "s|(^${var}$)|\1 ${*:2}|g" \
				-e "s|[[:space:]]+$||g" \
				-i -- ${cfg}
			ove_config_one ${cfg} ${var}
		fi
	fi
}

# helper function that updates/creates one OVE config file
function ove_update_config {
	local config
	local file
	local value

	file="$1"
	config="$2"
	value="$3"

	if ${ove_cmd2pathname["grep"]:?} -q "^${config} " ${file} &> /dev/null; then
		${ove_cmd2pathname["sed"]:?} -i "s|^${config} .*|${config} ${value}|g" ${file}
	else
		echo "${config} ${value}" >> ${file}
	fi
}

# add-config:file config value:add config/value pair to one OVE config file:CORE
function ove-add-config {
	ove_entry || return

	local config
	local file
	local value

	if [ $# -lt 3 ]; then
		ove_command_usage
		return 1
	fi

	if [ -e "$1" ]; then
		file=$(${ove_cmd2pathname["readlink"]:?} -f -- $1)
	else
		file=$1
	fi

	if ! ove_config_validate_filename ${file}; then
		ove_echo_error_noprefix "file '${file}' is not a valid OVE config file, select one of:"
		printf "%s\n" ${OVE_CONFIG_FILES_USER} 1>&2
		return 1
	fi
	config=$2
	if ! ove_read_config_validate_name ${config}; then
		ove_echo_error_noprefix "config name '${config}' is not allowed"
		return 1
	fi
	value="${*:3}"

	if [ -w "${file%/*}" ]; then
		ove_update_config "${file}" "${config}" "${value}"
		ove_reinit
	fi

	return 0
}

function ove_config_validate_filename {
	local f

	for f in ${OVE_CONFIG_FILES_ALL}; do
		if [ "$1" = "${f}" ]; then
			return 0
		fi
	done

	return 1
}

function ove_config_validate_file {
	local f

	f=$(${ove_cmd2pathname["readlink"]:?} -f -- $1)
	if [ ! -s "$f" ]; then
		return 1
	elif ! ove_config_validate_filename "${f}"; then
		return 1
	fi

	return 0
}

function ove_config2file {
	${ove_cmd2pathname["grep"]:?} -H "^${1} " \
		${OVE_CONFIG_FILES_ALL} 2> /dev/null | \
		${ove_cmd2pathname["tail"]:?} -1 | \
		${ove_cmd2pathname["cut"]:?} -d: -f1
}

function ove_list_oveconfig_files_user {
	local f
	local files

	for f in ${OVE_CONFIG_FILES_USER}; do
		if [ -e "${f}" ]; then
			files+=("${f}")
		fi
	done

	if [ ${#files[@]} -eq 0 ]; then
		return
	fi
	echo "${files[@]}"
}

function ove_list_oveconfig_files_all {
	local f
	local files

	for f in ${OVE_CONFIG_FILES_ALL}; do
		if [ -e "${f}" ]; then
			files+=("${f}")
		fi
	done

	if [ ${#files[@]} -eq 0 ]; then
		return
	fi
	echo "${files[@]}"
}

# config:[file[config[[value]]]]|[config[[value]]]:show/modify OVE config files, configs are read in order so last config takes precedence:CORE
function ove-config {
	ove_entry || return

	local cfg
	local cfg_diff
	local cfgs
	local d
	local grep_prefix
	local grep_postfix

	if [ $# -gt 0 ] && ove_config_validate_file $1; then
		cfgs=("${1}")
		shift
	else
		read -r -a cfgs < <(ove_list_oveconfig_files_user)
	fi

	if [ ${#cfgs[@]} -eq 0 ]; then
		ove_echo_cyan_noprefix "no '.oveconfig' file(s) found"
		return 1
	elif [ ${#cfgs[@]} -gt 1 ]; then
		grep_prefix="-H"
	fi

	# try to mark any local changes in ${OVE_OWEL_DIR}/.oveconfig
	grep_postfix='$'
	if ove_repo_cmd ${OVE_OWEL_DIR} ls-files --error-unmatch ${OVE_OWEL_DIR}/.oveconfig &> /dev/null; then
		# shellcheck disable=SC2016
		cfg_diff="$(ove_repo_cmd ${OVE_OWEL_DIR} diff --no-color -U1 --raw ${OVE_OWEL_DIR}/.oveconfig | \
			${ove_cmd2pathname["grep"]:?} '^+[A-Z]\+'| \
			${ove_cmd2pathname["cut"]:?} -b2- | \
			${ove_cmd2pathname["awk"]:?} '{print $1}')"
		for d in ${cfg_diff}; do
			grep_postfix+="|\b${d}\b"
		done
	fi

	# shellcheck disable=SC2126
	if [ $# -gt 1 ] && [ $(${ove_cmd2pathname["grep"]:?} "^${1} " "${cfgs[@]}" | ${ove_cmd2pathname["wc"]:?} -l) -gt 1 ]; then
		ove_echo_yellow_noprefix "'${1}' is present in more than one .oveconfig:"
		while true; do
			${ove_cmd2pathname["grep"]:?} "^${1} " "${cfgs[@]}" | ${ove_cmd2pathname["cut"]:?} -d: -f1
			read -r -p "config: "
			for cfg in "${cfgs[@]}"; do
				if [ "${REPLY}" = "${cfg}" ]; then
					cfgs=("${REPLY}")
					break 2
				fi
			done
			echo "error: try again, specify one of these files:" 1>&2
		done
	fi

	for cfg in "${cfgs[@]}"; do
		ove_config_one ${cfg} "$@"
	done | ${ove_cmd2pathname["sed"]:?} -e 's|^\(/.[^:]*\):|\1#|' -e 's| \+|#|' | ${ove_cmd2pathname["column"]:?} -t -s'#'

	if [ $# -gt 1 ]; then
		ove_reinit
	fi
}

# ls-files:[options]:git ls-files [options] for all git repositories:CORE
function ove-ls-files {
	ove_entry || return

	local opts

	if [ $# -eq 0 ]; then
		opts="--"
	else
		opts="$*"
	fi

	# shellcheck disable=SC2016
	ove_revtab_forall 'ove_repo_cmd ${repo} ls-files '"${opts}"' | ${ove_cmd2pathname["sed"]:?} -e "s|^|${repo}/|g"'
}

# list-modified-files: :list modified files:CORE
function ove-list-modified-files {
	ove_entry || return

	declare -a dirty_repos
	local cmd

	mapfile -t dirty_repos < <(ove_list_dirty_repos)
	if [ "${#dirty_repos}" -eq 0 ]; then
		return
	fi

	# shellcheck disable=SC2016
	cmd='ove_repo_cmd ${repo} "--no-pager diff-index" --quiet HEAD || ove_repo_cmd ${repo} diff --name-only HEAD | ${ove_cmd2pathname["sed"]:?} -e "s|^|${repo}/|g"'
	ove_revtab_forsome_parallel "${cmd}" 0 "${dirty_repos[@]}" 2> /dev/null | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
}

# list-modified-files-basename: :list modified files (basename):CORE
function ove-list-modified-files-basename {
	ove_entry || return

	ove-list-modified-files | ${ove_cmd2pathname["sed"]:?} "s|.*/||g" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
}

# list-committed-files:[days]:list committed files within 7 or days day(s):CORE
function ove-list-committed-files {
	ove_entry || return

	local cmd
	local days

	if [ $# -eq 1 ]; then
		days="$1"
	else
		days=7
	fi

	# shellcheck disable=SC2016
	cmd='ove_repo_cmd ${repo} "--no-pager log" --all --no-merges --author=\"$(${ove_cmd2pathname["git"]:?} config --get user.name)\" --name-only --pretty=format:\"\" --since=\"'${days}' days\" | while read line; do [ -f ${PWD}/${line} ] && echo -e ${PWD}/${line}; done'

	ove_revtab_forall_parallel "${cmd}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
}

function ove_uniq {
	if [ $# -eq 1 ]; then
		echo "${1}"
		return
	fi

	declare -A a_hash
	while [ $# -ne 0 ]; do
		if test "${a_hash["${1}"]+isset}"; then
			shift
			continue
		fi
		a_hash["${1}"]=1
		echo "${1}"
	done
}

function ove_edit {
	local a
	local b
	local editor
	local editor_cmd
	local editor_opt
	local f
	local files
	local files_by_epoch
	local line
	local ls_files=0
	local mod_files
	local refresh=0
	local res
	local skip=0

	editor="$1"
	shift

	# sanity check
	if ! ove_check_command "${editor}"; then
		return 1
	fi

	# check for files first
	for f in "$@"; do
		if [ -f "$f" ] || [ -h "$f" ]; then
			files+=("$(${ove_cmd2pathname["readlink"]:?} -f -- $f)")
		fi
	done

	# did we find all files already?
	if [ $# -ne 0 ] && [ $# -eq ${#files[@]} ]; then
		skip=1
	fi

	if [ $skip -eq 0 ]; then
		if [ -e ${OVE_OWEL_TMP_DIR}/ls-mod-files ]; then
			a=$(${ove_cmd2pathname["stat"]:?} --format '%Y' "${OVE_OWEL_TMP_DIR}/ls-mod-files")
			b=$(${ove_cmd2pathname["date"]:?} +%s)
			if [ $((b-a)) -gt $OVE_EDIT_LIFESPAN_TIME_IN_SEC ]; then
				refresh=1
			fi
		else
			refresh=1
		fi

		if [ $refresh -eq 1 ]; then
			ove-list-modified-files > ${OVE_OWEL_TMP_DIR}/ls-mod-files
		fi
		if [ -s ${OVE_OWEL_TMP_DIR}/ls-mod-files ]; then
			mapfile -t mod_files <<<"$(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/ls-mod-files)"
		fi
	fi

	# any modified files?
	if [ $skip -eq 0 ] && [ "${#mod_files[@]}" -ne 0 ]; then
		if [ $# -eq 0 ]; then
			if [ "${#mod_files[@]}" -gt 20 ]; then
				while read -r line; do
					if [ "$line" = "" ]; then
						continue
					fi
					files+=("${line}")
				done <<<"${mod_files[@]}"
			else
				# stat all modified files
				files_by_epoch=$(
				for f in "${mod_files[@]}"; do
					[ -e ${f} ] || continue
					echo $(${ove_cmd2pathname["stat"]:?} --format '%Y' ${f}):${f}
				done | \
					LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -r | \
					${ove_cmd2pathname["cut"]:?} -d: -f2)
				while read -r line; do
					if [ "$line" = "" ]; then
						continue
					fi
					files+=("${line}")
				done<<<"${files_by_epoch}"
			fi
		else
			# stat based on args
			files_by_epoch=$(
			for g in $(ove_uniq "$@"); do
				for f in "${mod_files[@]}"; do
					f_low=${f,,}
					if [[ ${f_low/${OVE_BASE_DIR}\/} == *${g,,}* ]] && [ -e ${f} ]; then
						echo $(${ove_cmd2pathname["stat"]:?} --format '%Y' ${f}):${f}
					fi
				done
			done | \
				LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -r | \
				${ove_cmd2pathname["cut"]:?} -d: -f2)
			while read -r line; do
				if [ "$line" = "" ]; then
					continue
				fi
				files+=("${line}")
			done <<<"${files_by_epoch}"
		fi
	fi

	# still no hits? try all files
	if [ $skip -eq 0 ] && [ "${#files[@]}" -eq 0 ]; then
		refresh=0
		if [ -e ${OVE_OWEL_TMP_DIR}/ls-files ]; then
			a=$(${ove_cmd2pathname["stat"]:?} --format '%Y' "${OVE_OWEL_TMP_DIR}/ls-files")
			b=$(${ove_cmd2pathname["date"]:?} +%s)
			if [ $((b-a)) -gt $OVE_EDIT_LIFESPAN_TIME_IN_SEC ]; then
				refresh=1
			fi
		else
			refresh=1
		fi
		if [ $refresh -eq 1 ]; then
			ove-ls-files > ${OVE_OWEL_TMP_DIR}/ls-files
		fi

		if [ $# -eq 0 ]; then
			mapfile -t files <<<"$(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/ls-files)"
		else
			for f in "$@"; do
				# a direct hit take precedence
				res=$(${ove_cmd2pathname["grep"]:?} "\/$f$" ${OVE_OWEL_TMP_DIR}/ls-files)
				if [ "$res" != "" ]; then
					while read -r line; do
						if [ "$line" = "" ]; then
							continue
						fi
						files+=("$line")
					done <<<"$res"
				else
					res=$(${ove_cmd2pathname["grep"]:?} "$f" ${OVE_OWEL_TMP_DIR}/ls-files)
					if [ "$res" != "" ]; then
						while read -r line; do
							if [ "$line" = "" ]; then
								continue
							fi
							files+=("$line")
						done <<<"$res"
					fi
				fi
			done
		fi
		ls_files=1
	fi

	if [ "${#files[@]}" -eq 0 ]; then
		return
	fi

	editor_opt=
	if [ "$editor" = "vi" ] || [ "$editor" = "gvim" ]; then
		if [ "$editor" = "gvim" ]; then
			editor_cmd="gvim"
		elif ! command -v vim > /dev/null; then
			editor_cmd="vi"
		else
			editor_cmd="vim"
		fi

		# sanity check
		if ! command -v ${editor_cmd} > /dev/null; then
			ove_command_not_found "${editor_cmd}"
			return 1
		fi

		# get rid of "N files to edit" msg
		if [ "${#files[@]}" -gt 1 ]; then
			editor_opt+=" --not-a-term"
		fi

		if [ $ls_files -eq 0 ]; then
			if [ "${#files[@]}" -gt 2 ]; then
				editor_opt+=" -c 'wincmd H'"
				editor_opt+=" -o"
			elif [ "${#files[@]}" -eq 2 ]; then
				editor_opt+=" -O"
			fi
		elif [ "${#files[@]}" -gt 1 ] && [ "${#files[@]}" -lt 20 ]; then
			editor_opt+=" -O"
		fi
	else
		editor_cmd="$editor"
	fi

	if [ "${#files[@]}" -gt 1 ] && [ $ls_files -eq 1 ]; then
		if ! command -v fzf > /dev/null; then
			printf "%s\n" "${files[@]}" | ${ove_cmd2pathname["cat"]:?} -n
			read -r -t 1
		else
			# launch fzf and vi
			# shellcheck disable=SC2016
			printf "%s\n" "${files[@]}" | \
				${ove_cmd2pathname["fzf"]:?} -m --bind "enter:execute(< /dev/tty eval \$(echo $editor_cmd $editor_opt {+}))" \
				--bind "left-click:execute(< /dev/tty eval \$(echo $editor_cmd $editor_opt {+}))" \
				--bind "ctrl-a:toggle-all" \
				--bind "ctrl-w:deselect-all" \
				--preview 'if [ ! -h {} ]; then head -$LINES {}; else find -L {} -xdev -type f -print0 | xargs -0 head -$LINES | head -$LINES; fi'
			return
		fi
	fi

	eval $editor_cmd $editor_opt $(ove_uniq "${files[@]}")
}

# emacs:[pattern|file...]:open files in emacs:UTIL
function ove-emacs {
	ove_entry || return

	ove_edit emacs "$@"
}

# vi:[pattern|file...]:open files in vi:UTIL
function ove-vi {
	ove_entry || return

	ove_edit vi "$@"
}

# gvim:[pattern|file...]:open files in gvim:UTIL
function ove-gvim {
	ove_entry || return

	ove_edit gvim "$@"
}

# edit:[pattern|file...]:open files in $EDITOR:UTIL
function ove-edit {
	ove_entry || return

	if [ "$EDITOR" = "" ]; then
		return 1
	fi

	ove_edit "${EDITOR}" "$@"
}

# helper function for mrproper
function ove_rmdir {
	local _dir
	local _files
	local _files_total

	if [ $# -ne 1 ]; then
		return 1
	fi

	if [ ! -d "$1" ]; then
		return 1
	fi

	_dir="$1"
	_files=$(${ove_cmd2pathname["find"]:?} ${_dir} -mindepth 1)
	if [ "${_files}" = "" ]; then
		return 1
	fi
	_files_total=$(printf "%s\n" ${_files} | ${ove_cmd2pathname["wc"]:?} -l)
	if [ ${_files_total} -eq 0 ]; then
		return 1
	fi

	printf "%s\n" ${_files}
	read -p "proceed to remove ${_files_total} files/directories (list above) from '${_dir}' using 'rm -rf'? (y/N) " -r
	if ! [[ ${REPLY} =~ ^[Yy]$ ]]; then
		return 1
	fi

	read -p "are you really sure? (y/N) " -r
	if ! [[ ${REPLY} =~ ^[Yy]$ ]]; then
		return 1
	fi

	${ove_cmd2pathname["find"]:?} "${_dir}" -mindepth 1 -print0 | ${ove_cmd2pathname["xargs"]:?} -0 rm -rfv
}

# mrproper:[y]:remove untracked repository files, '${OVE_STAGE_DIR}/*' and '${OVE_ARCHIVE_DIR}/*', USE WITH CARE:BUILD
function ove-mrproper {
	ove_entry || return

	local nbr_untracked_files

	if [ "$1" = "y" ]; then
		# shellcheck disable=SC2016
		ove_revtab_forall 'ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} "--no-pager clean" > /dev/null'
		if [ "${OVE_STAGE_DIR}" != "" ]; then
			${ove_cmd2pathname["rm"]:?} -rf ${OVE_STAGE_DIR:?}/*
		fi

		if [ "${OVE_ARCHIVE_DIR}" != "" ]; then
			${ove_cmd2pathname["rm"]:?} -rf ${OVE_ARCHIVE_DIR:?}/*
		fi

		return 0
	fi

	# shellcheck disable=SC2016
	nbr_untracked_files=$(ove_revtab_forall_parallel 'GIT_DRY_RUN=1 ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} clean' | ${ove_cmd2pathname["wc"]:?} -l)
	if [ "${nbr_untracked_files}" -ne 0 ]; then
		# dry-run first
		# shellcheck disable=SC2016
		ove_revtab_forall 'GIT_DRY_RUN=1 ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} "--no-pager clean" | ${ove_cmd2pathname["sed"]:?} -e "s|Would remove \(.*\)$|${PWD}/\1|g"'
		read -p "proceed to remove ${nbr_untracked_files} untracked files/directories (list above) using 'git clean'? (y/N) " -r
		if [[ ${REPLY} =~ ^[Yy]$ ]]; then
			read -p "are you really sure? (y/N) " -r
			if [[ ${REPLY} =~ ^[Yy]$ ]]; then
				# shellcheck disable=SC2016
				ove_revtab_forall 'ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} "--no-pager clean"'
			fi
		fi
	fi

	ove_rmdir "${OVE_STAGE_DIR}"
	ove_rmdir "${OVE_ARCHIVE_DIR}"

	return 0
}

# return a list of uniq directores for all repos
function ove_revtab_list_dirs_uniq {
	local c
	local d

	{
		for d in $(ove_revtab_list_fullpath); do
			c="$d"
			while true; do
				if [ "${c}" = "${OVE_BASE_DIR}" ]; then
					break
				fi
				c=${c%/*}
				printf "%s\n" "$c"
			done
		done
		printf "%s\n" $(ove_revtab_list_fullpath)
	} | ${ove_cmd2pathname["sort"]:?} -u
}

# wipe-base-dir:[y]:remove untracked files from ${OVE_BASE_DIR}, USE WITH CARE:CORE
function ove-wipe-base-dir {
	ove_entry || return

	local candidates
	local remove
	local reserved
	local rm_options="-i"

	if [ "${OVE_BASE_DIR}" = "${HOME}" ]; then
		ove_echo_error_noprefix "sorry, but you have to clean your home yourself (reason: \$OVE_BASE_DIR=\$HOME)"
		return 1
	fi

	# search for files/dirs
	mapfile -t candidates <<<"$(${ove_cmd2pathname["find"]:?} $OVE_BASE_DIR -mindepth 1 -maxdepth 1)"

	# sanity check
	if [ "${#candidates[@]}" -eq 1 ]; then
		ove_echo_fatal_noprefix "no candidates found, bash mapfile bug? bash version: ${BASH_VERSINFO[0]}.${BASH_VERSINFO[1]}"
		return 1
	fi

	# repos and some reserved files and directories
	read -a reserved -r <<<"$(echo $(ove_revtab_list_dirs_uniq) ${OVE_OWEL_DIR} ${OVE_STAGE_DIR} ${OVE_ARCHIVE_DIR} ${OVE_BASE_DIR}/{.owel,ove,.ove*,README*})"

	# compare candidates vs. reserved
	mapfile -t remove <<<"$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 \
		<(printf "%s\n" "${candidates[@]}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}) \
		<(printf "%s\n" "${reserved[@]}" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}))"

	# return early?
	if [ "${remove[0]}" = "" ]; then
		return
	fi

	if [ "$1" = "y" ]; then
		rm_options=""
	elif [ ${#remove[@]} -ge 2 ]; then
		echo "${remove[@]}" | ${ove_cmd2pathname["xargs"]:?} file | ${ove_cmd2pathname["cat"]:?} -n
		echo
	fi

	${ove_cmd2pathname["xargs"]:?} -a <(echo "${remove[@]}") rm -rf ${rm_options}

	return 0
}

function ove_set_lastlog {
	# shellcheck disable=SC2016
	OVE_LAST_COMMAND=$(ove-lastlog "${OVE_OWEL_NAME}" | \
		${ove_cmd2pathname["grep"]:?} "^${OVE_OWEL_NAME} " | \
		${ove_cmd2pathname["head"]:?} -1 | \
		${ove_cmd2pathname["awk"]:?} '{print $3}')
	if [ "${OVE_LAST_COMMAND}" = "" ]; then
		return 1
	fi

	return 0
}

# l:[pattern]:view last command output in pager (=${OVE_PAGER}) or print lines matching pattern:LOG
function ove-l {
	ove_entry || return

	if [ "$OVE_LAST_COMMAND" = "" ] && ! ove_set_lastlog; then
		return 1
	elif [ $# -eq 0 ]; then
		${OVE_PAGER} ${OVE_LAST_COMMAND}
		return $?
	fi

	if command -v ag > /dev/null; then
		${ove_cmd2pathname["ag"]:?} -H -i "$@" ${OVE_LAST_COMMAND}
	else
		echo ${OVE_LAST_COMMAND}
		${ove_cmd2pathname["grep"]:?} -i "$@" ${OVE_LAST_COMMAND}
	fi
}

# lr:[divisor]:short for 'ove-lastlog-replay $OVE_LAST_COMMAND':LOG
function ove-lr {
	ove_entry || return

	if [ "$OVE_LAST_COMMAND" = "" ] && ! ove_set_lastlog; then
		return 1
	fi

	ove-lastlog-replay $OVE_LAST_COMMAND $1
	return $?
}

# describe:[git...]:git describe+log+status combo for all/specified git repositories:CORE
function ove-describe {
	ove_entry || return

	local func

	func=ove_revtab_forall_parallel

	if [ $# -gt 0 ]; then
		func=ove_revtab_forsome
	fi

	# yes, this is ugly
	# shellcheck disable=SC1004,SC2016
	${func} 'echo $(\
		echo ${repo} | ${ove_cmd2pathname["sed"]:?} -e "s|${OVE_BASE_DIR}/||g")@$(ALLOW_OVERRIDE=1 ove_repo_cmd ${repo} describe 2> /dev/null)@"$(\
		${ove_cmd2pathname["git"]:?} log --format="%<(20,trunc)%s" -1 2> /dev/null \
		)"@"$(\
		${ove_cmd2pathname["git"]:?} -c color.status=never status -s -uno | \
		${ove_cmd2pathname["tr"]:?} "\n" " ")"' "$@" |\
		${ove_cmd2pathname["column"]:?} -t -s'@' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

# list-heads:[git...]:git log for all/specified git repositories:CORE
function ove-list-heads {
	ove_entry || return

	declare -a repos
	local cmd
	local func

	# shellcheck disable=SC2016
	cmd='echo $(echo -n "$(echo ${repo} | ${ove_cmd2pathname["sed"]:?} -e "s|${OVE_BASE_DIR}/||g")?" && '
	# shellcheck disable=SC2016
	cmd+='ove_repo_cmd ${repo} "--no-pager log" -1 --no-merges --format=%h?%ar?%ae?%s 2> /dev/null)'
	{
		if [ $# -eq 0 ]; then
			ove_revtab_forall "${cmd}"
		else
			mapfile -t repos < <(ove_validate_repo_list "$@")
			if [ "${#repos[@]}" -eq 0 ]; then
				return
			fi
			ove_revtab_forsome "${cmd}" "${repos[@]}"
		fi
	} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | ${ove_cmd2pathname["column"]:?} -t -s? 2> /dev/null
}

# ls-remote:[git...]:git ls-remote <remote.origin.url> HEAD for specified/all git repositories:CORE
function ove-ls-remote {
	ove_entry || return

	local i
	local r
	local repos
	local repo_shortpath
	local ret
	local sha
	local str
	local url

	if [ $# -ge 1 ]; then
		repos=$(ove_validate_repo_list "$@")
		if [ "${repos}" = "" ]; then
			return 1
		fi
	else
		repos=${OVE_REPO_LIST}
	fi

	for r in ${repos}; do
		repo_shortpath="$(ove_repo2shortpath ${r})"
		if [ "${repo_shortpath}" = "${OVE_OWEL_NAME}" ]; then
			url=$(ove_repo_cmd "${OVE_OWEL_DIR}" config --get remote.origin.url)
		else
			i=${ove_revtab_name2index[${repo_shortpath}]}
			url="${ove_revtab_fetch_url[${i}]}"
		fi

		if [ "${url}" = "" ] || [ "${url}" = "noremote" ]; then
			continue
		fi

		sha=$(ove_repo_cmd "${repo_shortpath}" ls-remote ${url} HEAD)
		sha=${sha%%[[:space:]]*}
		if [ "${sha}" = "" ]; then
			ove_echo_error_noprefix "ls-remote failed for '${url}'"
			(( ret+=1 ))
		else
			str+="${repo_shortpath}:${sha}\n"
		fi
	done

	printf "${str}" | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["column"]:?} -t -s:

	return ${ret}
}

# heads2revtab:[git...]:update 'revtab' with current SHA-1:CORE
function ove-heads2revtab {
	ove_entry || return
	ove_revtab_sanity || return

	local repo
	local repos
	local sha_1

	if [ $# -eq 0 ]; then
		repos=$(ove_revtab_list_basename)
	else
		repos=$*
	fi

	for repo in ${repos}; do
		if ! ove_dir_is_repo "${OVE_BASE_DIR}/${repo}"; then
			continue
		elif [ -n "${OVE_HEADS2REVTAB_MODE+x}" ] && \
			[ ${OVE_HEADS2REVTAB_MODE} -eq 1 ] && \
			! ${ove_cmd2pathname["git"]:?} -C "${OVE_BASE_DIR}/${repo}" symbolic-ref -q HEAD > /dev/null; then
			continue
		fi
		sha_1=$(ove_repo_cmd "${OVE_BASE_DIR}"/${repo} rev-parse HEAD)
		if [ "${sha_1}" = "" ]; then
			ove_echo_fatal_noprefix "empty SHA-1 for '${repo}'"
			continue
		fi
		${ove_cmd2pathname["sed"]:?} \
			-E \
			-e 's|^'${repo}'([[:space:]]+.*[[:space:]]+.*[[:space:]]+)(.*)$|'${repo}'\1'${sha_1}'|g' \
			-i \
			-- "${OVE_OWEL_DIR}"/revtab
	done

	ove_repo_cmd "${OVE_OWEL_DIR}" "--no-pager diff" revtab
}

# head-tail:file [num]:display first/last 3(=num) lines of a text file:UTIL
function ove-head-tail {
	ove_entry || return

	local c
	local f
	local n

	if [[ $# -eq 0 || $# -gt 2 || ( $# -eq 2 && ! "$2" =~ ^[0-9]+$ ) ]]; then
		ove_command_usage
		return 1
	fi

	f=$1
	if ! [ -e ${f} ]; then
		ove_echo_error_noprefix "file '${f}' not found"
		return 1
	fi

	if ! ${ove_cmd2pathname["file"]:?} -bL --mime ${f} | ${ove_cmd2pathname["grep"]:?} -q '^text'; then
		ove_echo_error_noprefix "'${f}' is not a text file, use xxd/hexdump"
		return 1
	fi

	if [ $# -eq 1 ]; then
		c=3
	else
		c=$2
	fi
	n=$(${ove_cmd2pathname["wc"]:?} -l <${f})
	if [ ${n} -gt $((c + c)) ]; then
		${ove_cmd2pathname["cat"]:?} -n ${f} | ${ove_cmd2pathname["head"]:?} -${c}
		echo -e "\t..."
		${ove_cmd2pathname["cat"]:?} -n ${f} | ${ove_cmd2pathname["tail"]:?} -${c}
	else
		${ove_cmd2pathname["cat"]:?} -n ${f}
	fi
}

# what-extensions:dir...:classify files inside 'dir' based on file extensions:UTIL
function ove-what-extensions {
	ove_entry || return

	local dir

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	for dir in "$@"; do
		if [ ! -d "${dir}" ]; then
			continue
		fi
		echo "$(${ove_cmd2pathname["readlink"]:?} -f -- ${dir}):"
		${ove_cmd2pathname["find"]:?} \
			"${dir}" \
			-not -path '*/.git/*' \
			-name '*.*' \
			-printf "%f\n" \
			2> /dev/null | \
		${ove_cmd2pathname["grep"]:?} -v '^\.' | \
		${ove_cmd2pathname["rev"]:?} | \
		${ove_cmd2pathname["cut"]:?} -d'.' -f1 | \
		${ove_cmd2pathname["rev"]:?} | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["uniq"]:?} -c | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr
	done
}

# what-is:dir...:classify files inside 'dir' using 'file':UTIL
function ove-what-is {
	ove_entry || return

	local dir

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	for dir in "$@"; do
		if [ ! -d "${dir}" ]; then
			continue
		fi
		echo "$(${ove_cmd2pathname["readlink"]:?} -f -- ${dir}):"
		# shellcheck disable=SC2016
		${ove_cmd2pathname["find"]:?} \
			"${dir}" \
			-not -path '*/.git/*' \
			-print0 \
			2> /dev/null | \
			${ove_cmd2pathname["xargs"]:?} -0 ${ove_cmd2pathname["file"]:?} | \
			${ove_cmd2pathname["awk"]:?} '{$1=""; print $0}' | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
			${ove_cmd2pathname["uniq"]:?} -c | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr
	done
}

# show:[rev...]:ove list-heads or search for 'rev' within all git repositories. If found run 'git show rev':CORE
function ove-show {
	ove_entry || return

	local revision

	if [ $# -eq 0 ]; then
		ove-list-heads
		return
	fi

	for revision in "$@"; do
		# remove dirty tags
		revision=${revision%-dirty}
		ove_revtab_forall "
		if ove_repo_cmd \${repo} '--no-pager show' ${revision} -- &> /dev/null; then \
			clear; \
			if [ ${OVE_LESS_MORE_OPTIONS} -eq 1 ]; then
				less_opt=\"-X -R -Ps\${repo_basename} ${revision//./\\.}\";
			else
				less_opt=\"-R\";
			fi;
			LESS=\${less_opt} ALLOW_OVERRIDE=1 ove_repo_cmd \${repo} '-p show' ${revision} --;
			unset less_opt
		fi"
	done
}

# cd:[pattern|@] :'cd ${OVE_BASE_DIR}' OR switch to a OVE workspace specified by pattern:CORE
function ove-cd {
	if [ $# -eq 0 ]; then
		if ! cd "${OVE_BASE_DIR}"; then
			return 1
		fi
	elif [ $# -eq 1 ] && [ "$1" = "@" ]; then
		ove_set_workspace
	else
		ove_set_workspace "$@"
	fi
}

# version: :print OVE version:CORE
function ove-version {
	ove_entry || return

	local s

	s="OVE ${OVE_SHA} | ${OVE_OS} ${OVE_OS_VER}"
	if [ "${OVE_OS_KERNEL:?}" != "" ]; then
		s+=" | ${OVE_OS_KERNEL}"
	fi
	echo "${s}"
}

# revtab-check:[0|1]:disable/enable if OVE should keep repos in-sync with 'revtab':CORE
function ove-revtab-check {
	ove_entry || return

	local cfg
	local reinit=0

	if [ $# -eq 1 ] && ! [[ "${1}" =~ ^[0-1]$ ]]; then
		ove_command_usage
		return 1
	elif [ $# -eq 1 ]; then
		if [ ${OVE_REVTAB_CHECK} -eq 0 ] && [ ${1} -eq 1 ]; then
			reinit=1
		fi

		OVE_REVTAB_CHECK=$1

		cfg=$(ove_config2file OVE_REVTAB_CHECK)
		if [ "${cfg}" = "" ]; then
			cfg="${OVE_OWEL_STATE_DIR}/.oveconfig"
		fi
		ove-add-config ${cfg} OVE_REVTAB_CHECK ${OVE_REVTAB_CHECK}
	fi

	if [ ${OVE_REVTAB_CHECK} -eq 1 ]; then
		echo "revtab check (=OVE_REVTAB_CHECK) is ENABLED for this workspace"
		if [ ${reinit} -eq 1 ]; then
			ove_reinit
		fi
	else
		echo "revtab check (=OVE_REVTAB_CHECK) is DISABLED for this workspace"
	fi
}

# loglevel:[level]:show or change loglevel [0-10]:DEBUG
function ove-loglevel {
	ove_entry || return

	local cfg
	local prefix
	local sysctl_f

	set +x
	if [ $# -eq 1 ] && ! [[ "${1}" =~ ^[0-9]+$ ]]; then
		ove_command_usage
		return 1
	elif [ $# -eq 1 ] && [ "${1}" -gt 10 ]; then
		ove_command_usage
		return 1
	elif [ $# -eq 1 ]; then
		if [ $1 -gt 2 ] && [ $1 -lt 11 ]; then
			if ! ove_check_command "strace"; then
				return 1
			fi

			if [ -e /proc/sys/kernel/yama/ptrace_scope ] && [ $(${ove_cmd2pathname["cat"]:?} /proc/sys/kernel/yama/ptrace_scope) -ne 0 ]; then
				ove_echo_error_noprefix "the kernel does not allow you to trace all processes"
				echo
				echo "To fix this for now:"
				if [ ${EUID} != 0 ]; then
					prefix="sudo"
				fi
				echo " ${prefix} ${ove_cmd2pathname["bash"]:?} -c 'echo 0 > /proc/sys/kernel/yama/ptrace_scope'"
				echo
				echo "To fix this permanently:"
				sysctl_f=$(${ove_cmd2pathname["grep"]:?} -l kernel.yama.ptrace_scope /etc/sysctl.d/*)
				if [ "${sysctl_f}" != "" ]; then
					echo " ${prefix} ${ove_cmd2pathname["bash"]:?} -c 'echo 0 > /proc/sys/kernel/yama/ptrace_scope; sed -i -e \"s/kernel.yama.ptrace_scope.*/kernel.yama.ptrace_scope = 0/g\" ${sysctl_f}'"
				else
					echo " ${prefix} ${ove_cmd2pathname["bash"]:?} -c 'echo 0 > /proc/sys/kernel/yama/ptrace_scope; echo \"kernel.yama.ptrace_scope = 0\" > /etc/sysctl.d/10-ptrace.conf'"
				fi
				return 1
			fi
		fi

		OVE_LOGLEVEL=$1
		cfg=$(ove_config2file OVE_LOGLEVEL)
		if [ "${cfg}" = "" ]; then
			cfg="${OVE_OWEL_STATE_DIR}/.oveconfig"
		fi
		ove-add-config ${cfg} OVE_LOGLEVEL $1
	fi

	{
		echo "0@silence is golden"
		echo "1@normal"
		echo "2@debug@[set -x]"
		echo "3@execve timeline@[strace]"
		echo "4@execve time analysis@[strace]"
		echo "5@connect analysis@[strace]"
		echo "6@graph analysis@[strace]"
		echo "7@file (all)@[strace]"
		echo "8@file (-z/ok)@[strace]"
		echo "9@file (-Z/nok)@[strace]"
		echo "10@raw@[strace]"
	} | ${ove_cmd2pathname["column"]:?} -t -s'@' | \
		${ove_cmd2pathname["grep"]:?} -E --color "$|^${OVE_LOGLEVEL} .*"

	if [ $# -eq 1 ]; then
		OVE_REDIRECT_OUTPUT=""
		if [ $1 -eq 0 ]; then
			OVE_REDIRECT_OUTPUT="> /dev/null"
		elif [ $1 -eq 1 ]; then
			set +x
		elif [ $1 -eq 2 ]; then
			set -x
		fi
	fi
}

# dry-run:[0|1]:toggle or set OVE_DRY_RUN:DEBUG
function ove-dry-run {
	ove_entry || return

	if [ $# -eq 1 ] && ! [[ "$1" =~ ^[0-1]$ ]]; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 0 ]; then
		OVE_DRY_RUN=$((OVE_DRY_RUN ^= 1))
	else
		OVE_DRY_RUN=$1
	fi

	ove-env ^OVE_DRY_RUN
}

# rec:[0|1]:toggle or set screen recording:UTIL
function ove-rec {
	ove_entry || return

	if [ $# -eq 1 ] && ! [[ "$1" =~ ^[0-1]$ ]]; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 0 ]; then
		OVE_RECORD_IT=$((OVE_RECORD_IT ^= 1))
	else
		OVE_RECORD_IT=$1
	fi

	ove-env ^OVE_RECORD_IT
}

# lastlog-summary:[pattern]:peek inside OVE logs and make a summary:LOG
function ove-lastlog-summary {
	ove_entry || return

	local cmd
	local d
	local diff_s
	local exit_code
	local f
	local f_base
	local ff
	local first
	local last
	local log_type
	local second
	local self=${FUNCNAME[0]/ove-/}
	local t
	local t0="NA"
	local t1="NA"
	local u

	# ignore logs before October 1, 2021
	${ove_cmd2pathname["touch"]:?} -t 202110010000 $OVE_TMP/ove-${self}-ref
	${ove_cmd2pathname["find"]:?} /var/tmp/*/ove/logs -type f -name '2*.log' -newer $OVE_TMP/ove-${self}-ref -print  > $OVE_TMP/ove-${self}
	${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}-ref
	if [ ! -s $OVE_TMP/ove-${self} ]; then
		echo "error: no logs found" 1>&2
		if [ -e $OVE_TMP/ove-${self} ]; then
			${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}
		fi
		return 1
	elif [ $# -ne 0 ]; then
		${ove_cmd2pathname["grep"]:?} -E -i ".*$1.*" $OVE_TMP/ove-${self} > $OVE_TMP/ove-${self}.filter
		if [ ! -s $OVE_TMP/ove-${self}.filter ]; then
			echo "error: no logs found after filter" 1>&2
			if [ -e $OVE_TMP/ove-${self}.filter ]; then
				${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}.filter
			fi
			return 1
		fi
		${ove_cmd2pathname["mv"]:?} $OVE_TMP/ove-${self}.filter $OVE_TMP/ove-${self}
	fi

	printf "%-24s %-4s %-8s %s\n" "date" "exit" "sec" "command"
	for f in $(${ove_cmd2pathname["xargs"]:?} stat --format '%Y:%n' < $OVE_TMP/ove-${self} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr); do
		t=${f%%:*}
		ff=${f#*:}

		first=
		second=
		last=
		exit_code=
		t0="NA"
		t1="NA"
		diff_s="NA"
		while read -r line; do
			if [ "$first" = "" ]; then
				first=${line}
			elif [ "$second" = "" ]; then
				second=${line}
				break
			fi
		done <$ff;

		if [[ $first == "Script started"* ]]; then
			log_type="script"
			last=$(${ove_cmd2pathname["tail"]:?} -1 $ff)
			t0=${first/Script started on }
			t0=${t0%%[*}
			if ! t0=$(${ove_cmd2pathname["date"]:?} -d "$t0" '+%s' 2> /dev/null); then
				t0="NA"
			fi
		else
			log_type="tee"
		fi

		if [ "$log_type" = "script" ]; then
			cmd=$second
			# remove CR
			cmd=${cmd//$'\r'/}
			if [[ $last == "Script done"* ]]; then
				exit_code=${last/*COMMAND_EXIT_CODE=\"}
				exit_code=${exit_code%\"*}
				t1=${last/Script done on }
				t1=${t1%% [*}
				if ! t1=$(${ove_cmd2pathname["date"]:?} -d "$t1" '+%s' 2> /dev/null); then
					t1="NA"
				fi
			fi
		elif [ "$log_type" = "tee" ]; then
			cmd=$first
			exit_code=${cmd//*# exit code: /}
			cmd=${cmd/\# exit code:*/}
		fi

		if [ ${EUID} -eq 0 ] && [[ $cmd != \#* ]]; then
			continue
		elif [ ${EUID} -ne 0 ] && [[ $cmd != \$* ]]; then
			continue
		fi

		if [ "$t0" != "NA" ] && [ "$t1" != "NA" ]; then
			diff_s=$((t1-t0))
		fi

		if [ "$exit_code" = "" ]; then
			exit_code="NA"
		elif ! [[ "${exit_code}" =~ ^[0-9]+$ ]]; then
			exit_code="NA"
		fi

		if [ "$cmd" = "" ]; then
			cmd="unknown"
		else
			if [ "${cmd: -1}" = " " ]; then
				# remove trailing whitespace
				cmd=${cmd::-1}
			fi
			cmd=${cmd:2}

			if [[ $cmd != ove* ]]; then
				cmd="unknown"
			fi
		fi

		f_base=${ff##*/}
		d=${f_base:0:24}
		u=${ff#*/}
		u=${u#*/}
		u=${u#*/}
		u=${u%%/*}
		if [ "$u" = "$OVE_USER" ]; then
			printf "%-24s %-4s %-8s %s\n" $d $exit_code ${diff_s} "$cmd"
		else
			printf "%-24s %-10s %-3s %-8s %s\n" $d $u $exit_code ${diff_s} "$cmd"
		fi
	done

	if [ -e "$OVE_TMP/ove-${self}" ]; then
		${ove_cmd2pathname["rm"]:?} "$OVE_TMP/ove-${self}"
	fi

	return 0
}

# demo:[git...|pattern]:run 'lastlog-replay' on logs found at '<git>/.ove/demo', '<OVE_OWEL_DIR>/demo' or '<OVE_DIR>/demo':UTIL
function ove-demo {
	ove_entry || return

	local d
	declare demos
	local demo_list
	local p
	local re
	local repo
	local repo_fullpath
	local repos

	if [ $# -ge 1 ]; then
		repos=$(ove_validate_repo_list "$@")
	else
		repos="${OVE_REPO_LIST}"
	fi

	if [ $# -eq 1 ] && [ "${repos}" = "" ]; then
		re="$1"
		repos="${OVE_REPO_LIST}"
	fi

	demos=()
	for repo in ${repos}; do
		repo_fullpath=$(ove_repo2fullpath $repo)

		if [ "${repo_fullpath}" = "${OVE_BASE_DIR}/${OVE_OWEL_NAME}" ]; then
			p="${OVE_BASE_DIR}/${OVE_OWEL_NAME}/demo"
		elif [ "${repo_fullpath}" = "${OVE_DIR}" ]; then
			p="${OVE_DIR}/demo"
		else
			p="${repo_fullpath}/.ove/demo"
		fi

		if [ ! -d "${p}" ]; then
			continue
		fi

		demo_list=$(${ove_cmd2pathname["find"]:?} -L ${p} -name '*.log' -type f | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
		for d in ${demo_list}; do
			if [ "${re}" != "" ]; then
				if [[ $d =~ $re ]]; then
					demos+=("${d/.log/}")
				fi
				continue
			fi
			demos+=("${d/.log/}")
		done
	done

	if [ "${demo_list}" = "" ]; then
		echo "no demos found" 1>&2
		return 0
	elif [ ${#demos[@]} -eq 0 ]; then
		echo "no demos found, available demos:" 1>&2
		printf "%s\n" "${demo_list}" | ${ove_cmd2pathname["cat"]:?} -n 1>&2
		return 0
	fi

	for d in "${!demos[@]}"; do
		if [ -s "${demos[$d]}".pre ]; then
			if ! source "${demos[$d]}".pre; then
				continue
			fi
		fi

		ove-lastlog-replay "${demos[$d]}".log ${OVE_DEMO_DIVISOR}

		if [ -s "${demos[$d]}".post ]; then
			source "${demos[$d]}".post
		fi
	done
}

# lastlog-replay:[file [divisor]]|[pattern [divisor]]:replay OVE commands:LOG
function ove-lastlog-replay {
	ove_entry || return

	local d
	local divisor=1
	local f
	local ff
	local self=${FUNCNAME[0]/ove-/}

	if [ $# -ne 0 ] && [ -s "$1" ]; then
		echo "$1" > $OVE_TMP/ove-${self}
		if [ $# -eq 2 ]; then
			if [[ ! "${2}" =~ ^[0-9]+$ ]]; then
				echo "error: just numbers" 1>&2
				ove_command_usage
				return 1
			fi
			divisor=$2
		fi
	else
		# ignore logs before October 18, 2021
		${ove_cmd2pathname["touch"]:?} -t 202110180000 $OVE_TMP/ove-${self}-ref
		${ove_cmd2pathname["find"]:?} /var/tmp/*/ove/logs -type f -name '2*' -newer $OVE_TMP/ove-${self}-ref -not -name '*.timing' -print  > $OVE_TMP/ove-${self}
		${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}-ref
		if [ ! -s $OVE_TMP/ove-${self} ]; then
			echo "error: no logs found" 1>&2
			if [ -e $OVE_TMP/ove-${self} ]; then
				${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}
			fi
			return 1
		elif [ $# -ne 0 ]; then
			${ove_cmd2pathname["grep"]:?} -E -i ".*$1.*" $OVE_TMP/ove-${self} > $OVE_TMP/ove-${self}.filter
			if [ ! -s $OVE_TMP/ove-${self}.filter ]; then
				echo "error: no logs found after filter" 1>&2
				if [ -e $OVE_TMP/ove-${self}.filter ]; then
					${ove_cmd2pathname["rm"]:?} $OVE_TMP/ove-${self}.filter
				fi
				return 1
			fi
			${ove_cmd2pathname["mv"]:?} $OVE_TMP/ove-${self}.filter $OVE_TMP/ove-${self}
		fi

		if [ $# -eq 2 ]; then
			divisor=$2
		fi
	fi

	for f in $(${ove_cmd2pathname["xargs"]:?} stat --format '%Y:%n' < $OVE_TMP/ove-${self} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -n); do
		ff=${f#*:}
		if [ ! -e ${ff/.log}.timing ]; then
			continue
		fi
		d=${ff##*/}
		# truncate ove logs and just show the date
		if [[ $d = 2*-ove-* ]]; then
			d=${d:0:22}
		fi
		ove_echo_cyan_noprefix "$d"
		if ! ${ove_cmd2pathname["scriptreplay"]:?} -m 3 --divisor $divisor --timing ${ff/.log}.timing $ff 2> /dev/null; then
			ove_echo_error_noprefix "scriptreplay failed"
		fi
	done

	if [ -e "$OVE_TMP/ove-${self}" ]; then
		${ove_cmd2pathname["rm"]:?} "$OVE_TMP/ove-${self}"
	fi

	return 0
}

# lastlog:[pattern]:list OVE logs:LOG
function ove-lastlog {
	ove_entry || return

	local find_opt
	local pattern
	local self=${FUNCNAME[0]/ove-/}

	${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} -name "2*$HOSTNAME*.log" -type f ${find_opt} -print > $OVE_TMP/ove-${self}
	if [ ! -s $OVE_TMP/ove-${self} ]; then
		echo "error: no logs found" 1>&2
		return 1
	elif [ $# -eq 0 ]; then
		pattern=$(${ove_cmd2pathname["date"]:?} '+%Y%m%d')
	else
		pattern=$1
	fi

	${ove_cmd2pathname["grep"]:?} -E -i ".*$pattern.*" $OVE_TMP/ove-${self} > $OVE_TMP/ove-${self}.filter
	if [ ! -s $OVE_TMP/ove-${self}.filter ]; then
		echo "error: no logs found after filter" 1>&2
		return 1
	fi
	${ove_cmd2pathname["mv"]:?} $OVE_TMP/ove-${self}.filter $OVE_TMP/ove-${self}

	${ove_cmd2pathname["xargs"]:?} stat --format '%Y:%n:%s' < $OVE_TMP/ove-${self}| \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr | \
		${ove_cmd2pathname["cut"]:?} -d: -f2- | \
		${ove_cmd2pathname["grep"]:?} -v ${FUNCNAME[0]} | \
		${ove_cmd2pathname["sed"]:?} "s/\(^.*-ove-\(.*\)-${HOSTNAME}-\(.*\).log\):\(.*\)/\3@\2@\1@\4/g" | \
		${ove_cmd2pathname["column"]:?} -t -s@
}

# rm-logs:[days [y]]:remove OVE logs older than 30|days days. days=0 => all logs:LOG
function ove-rm-logs {
	ove_entry || return

	local days=30
	local find_opt="-mtime +${days}"
	local interactive=1

	if  [ $# -gt 2 ]; then
		ove_command_usage
		return 1
	elif [ $# -eq 2 ] && [ "$2" != "y" ]; then
		ove_command_usage
		return 1
	fi

	if [ $# -eq 2 ]; then
		interactive=0
	fi

	if [ $# -gt 0 ]; then
		if ! [[ "${1}" =~ ^[0-9]+$ ]]; then
			echo "error: just numbers" 1>&2
			ove_command_usage
			return 1
		fi

		if [ $1 -eq 0 ]; then
			find_opt=""
		else
			days=$1
			find_opt="-mtime +${days}"
		fi
	fi

	find_opt="-maxdepth 2 -type f ${find_opt} -print"

	if [ "$(${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} ${find_opt} -quit)" = "" ]; then
		if [ ${interactive} -eq 1 ]; then
			ove_echo_error_noprefix "no OVE log files older than ${days} days found here: ${OVE_LOG_DIR}"
		fi
		return 1
	fi

	if [ ${interactive} -eq 1 ]; then
		${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} ${find_opt} | ${ove_cmd2pathname["cat"]:?} -n

		echo
		echo -n "proceed to remove "
		if [ $# -eq 1 ] && [ $1 -eq 0 ]; then
			read -p "ALL files (list above) from '${OVE_LOG_DIR}' (y/N) " -r
		else
			read -p "files older than ${days} days (list above) from '${OVE_LOG_DIR}' (y/N) " -r
		fi
		if [[ ! ${REPLY} =~ ^[Yy]$ ]]; then
			return 1
		fi
		read -p "are you really sure? (y/N) " -r
		if [[ ! ${REPLY} =~ ^[Yy]$ ]]; then
			return 1
		fi
	fi

	if [ "${OVE_LAST_COMMAND}" != "" ]; then
		${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} ${find_opt} | \
			${ove_cmd2pathname["grep"]:?} -v ${OVE_LAST_COMMAND} | \
			${ove_cmd2pathname["xargs"]:?} rm -v
	else
		find_opt+="0"
		${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} ${find_opt} | \
			${ove_cmd2pathname["xargs"]:?} -0 rm -v
	fi
	${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} -maxdepth 1 -empty -type d -delete

	return 0
}

# export-logs: :export OVE logs:LOG
function ove-export-logs {
	local o

	if [ "$(${ove_cmd2pathname["find"]:?} ${OVE_LOG_DIR} -name "2*$HOSTNAME*.log" -type f -print 2> /dev/null | head -1)" = "" ]; then
		ove_echo_error_noprefix "no logs found"
		return 1
	fi

	o="$(pwd -P)"
	if [ ! -w "${o}" ]; then
		o="${OVE_TMP:?}"
	fi
	o+="/ove-logs-$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S')-${HOSTNAME}.tar.bz2"
	if ! ${ove_cmd2pathname["tar"]:?} -C "${OVE_LOG_DIR}" --owner=0 --group=0 -cjf "${o}" .; then
		return 1
	fi
	echo "${o}"

	return 0
}

# authors: :list author summary for all git repositories:UTIL
function ove-authors {
	ove_entry || return

	local repo

	declare -A urls

	for repo in ${OVE_REPO_LIST}; do
		if [ ! -d "${repo}" ] || [ "${repo}" = "${OVE_DIR}" ]; then
			continue
		fi

		# Try to avoid that a git is counted more than one time
		url=$(ove_repo_cmd "${repo}" "--no-pager remote" -v | \
			${ove_cmd2pathname["grep"]:?} fetch | \
			${ove_cmd2pathname["cut"]:?} -f2 | \
			${ove_cmd2pathname["cut"]:?} -d' ' -f1 | \
			${ove_cmd2pathname["uniq"]:?} | \
			${ove_cmd2pathname["sed"]:?} -e 's/[^a-zA-Z0-9\-]/_/g' | \
			${ove_cmd2pathname["sed"]:?} -e 's/_git$//g')

		if [ "${url}" != "" ]; then
			if test "${urls["${url}"]+isset}"; then
				continue
			fi
			urls["${url}"]=1
		fi

		ove_repo_cmd "${repo}" "--no-pager log" --pretty="%ae"
	done | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["uniq"]:?} -c | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr
}

# domains: :list email domain summary for all git repositories:UTIL
function ove-domains {
	ove_entry || return

	ove-authors | \
		${ove_cmd2pathname["grep"]:?} '@' | \
		${ove_cmd2pathname["cut"]:?} -d@ -f2 | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["uniq"]:?} -c | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -nr
}

function ove_bash_complete {
	local a
	local b
	local cmd
	local cur
	local refresh
	local opts
	local size
	local subcommand
	local wordlist

	# sanity check
	if ! ove_get_base_dir &> /dev/null; then
		return 1
	fi

	if ! ove_verify_checksums && ! ove_reinit; then
		return 1
	fi

	COMPREPLY=()

	cur="${COMP_WORDS[COMP_CWORD]}"
	subcommand="${COMP_WORDS[1]}"
	size=$((${#COMP_WORDS[@]} - 1))

	# project commands
	for cmd in ${OVE_PROJECT_COMMANDS}; do
		if [ "${cmd}" = "${subcommand}" ] ||
			[ "${cmd}-parallel" = "${subcommand}" ]; then
			if [ ${size} -ge 2 ]; then
				mapfile -t COMPREPLY < <(compgen -W "${OVE_PROJECT_LIST} ${!ove_projects_tags[*]}" -- "${cur}")
				return
			fi
		fi
	done

	# scripts
	for cmd in ${OVE_SCRIPTS_LIST}; do
		if [ "${cmd}" = "${subcommand}" ] && [ -e "${ove_scripts_name2path[${cmd}]}/${cmd}.complete" ]; then
			source "${ove_scripts_name2path[${cmd}]}/${cmd}.complete"
			return
		fi
	done

	# commands without arguments: do nothing
	if [ ${size} -eq 2 ]; then
		while read -r line; do
			if [ "$line" = "${subcommand}" ]; then
				return
			fi
		done <<<$(printf "%s\n" ${OVE_BUILT_INS_WITHOUT_ARGS:?})
	fi

	wordlist=""
	if [ "${subcommand}" = "make" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="${OVE_PROJECT_LIST}"
			wordlist+=" ${OVE_PROJECT_LIST// /-nodeps }-nodeps"
		elif [ ${size} -gt 2 ]; then
			return
		fi
	elif [ "${subcommand}" = "buildme" ] ||
		[ "${subcommand}" = "buildme-parallel" ] ||
		[[ "${subcommand}" == *cleanme ]] ||
		[ "${subcommand}" = "export" ] ||
		[ "${subcommand}" = "install-pkg" ] ||
		[ "${subcommand}" = "list-deps" ] ||
		[ "${subcommand}" = "list-needs" ] ||
		[ "${subcommand}" = "list-missing-projects" ] ||
		[ "${subcommand}" = "list-path" ] ||
		[ "${subcommand}" = "proj2val" ] ||
		[ "${subcommand}" = "list-projects" ]; then
		if [[ $cur == +* ]] || [[ $cur == -* ]]; then
			wordlist=$(printf "\${cur:0:1}%s " $OVE_PROJECT_LIST)
			if [ ${#ove_projects_tags[*]} -ne 0 ]; then
				a="${!ove_projects_tags[*]}"
				wordlist+=" $(printf "\${cur:0:1}%s " ${a})"
			fi
		else
			wordlist=${OVE_PROJECT_LIST}
			if [ ${#ove_projects_tags[*]} -ne 0 ]; then
				wordlist+=" ${!ove_projects_tags[*]}"
			fi
		fi
		if [ "${subcommand}" = "proj2val" ] && [ ${size} -ge 3 ]; then
			wordlist+=" deps needs path version"
		fi
	elif [ "${subcommand}" = "distrocheck" ] ||
		[ "${subcommand}" = "distrocheck-parallel" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(${ove_cmd2pathname["find"]:?} ${OVE_OWEL_DIR}/projects/*/ -name 'distcheck' -exec dirname {} \; 2> /dev/null)
			if [ "${wordlist}" != "" ]; then
				wordlist=${wordlist//${OVE_OWEL_DIR}\/projects\/}
			else
				wordlist=${OVE_PROJECT_LIST}
			fi
		elif [ ${size} -ge 3 ] && [ -s "${OVE_GLOBAL_STATE_DIR}/distrocheck.images" ]; then
			wordlist=$(${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/distrocheck.images")
		elif [ ${size} -eq 3 ]; then
			if ove-refresh-image &> /dev/null; then
				wordlist=$(${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/distrocheck.images")
			fi
		else
			return
		fi
	elif [ "${subcommand}" = "distrocheck-all" ]; then
		if [ ${size} -ge 2 ] && [ -s "${OVE_GLOBAL_STATE_DIR}/distrocheck.images" ]; then
			wordlist=$(${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/distrocheck.images")
		elif [ ${size} -eq 2 ]; then
			if ove-refresh-image &> /dev/null; then
				wordlist=$(${ove_cmd2pathname["cat"]:?} "${OVE_GLOBAL_STATE_DIR}/distrocheck.images")
			fi
		else
			return
		fi
	elif [ "${subcommand}" = "run" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="TIMEOUT"
		elif [ ${size} -eq 3 ]; then
			wordlist="${OVE_ALL_COMMANDS}"
		else
			return
		fi
	elif [ "${subcommand}" = "setup" ]; then
		if [ ${size} -eq 3 ] && [ -d $OVE_GLOBAL_STATE_DIR/hub ]; then
			# shellcheck disable=SC2016
			wordlist=$(ove-list-hub | ${ove_cmd2pathname["sed"]:?} -e 's,.*\/,,g')
		fi
	elif [ "${subcommand}" = "run-parallel" ]; then
		if [ $((size%2)) -eq 0 ]; then
			wordlist="TIMEOUT"
		elif [ $((size%2)) -eq 1 ]; then
			wordlist="${OVE_ALL_COMMANDS}"
		fi
	elif [ "${subcommand}" = "loop" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="TIMEOUT"
		elif [ ${size} -eq 3 ]; then
			wordlist="INOTIFY"
		elif [ ${size} -eq 4 ]; then
			wordlist="MAX-COUNT"
		elif [ ${size} -eq 5 ]; then
			wordlist="${OVE_ALL_COMMANDS}"
		else
			return
		fi
	elif [ "${subcommand}" = "ide" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="close reopen"
		fi
	elif [ "${subcommand}" = "update-revtab" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(ove_revtab_list_basename)
		elif  [ ${size} -eq 3 ]; then
			wordlist=$(ove_list_tags_and_branches ${OVE_BASE_DIR}/${COMP_WORDS[2]})
		fi
	elif [ "${subcommand}" = "checkout" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(ove_list_tags_and_branches)
		elif [ ${size} -eq 3 ]; then
			wordlist="purge autostash"
		else
			return
		fi
	elif [ "${subcommand}" = "fzf" ]; then
		if [ ${size} -ne 2 ]; then
			return
		fi
		wordlist="loop"
	elif [ "${subcommand}" = "stash" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="drop list pop show push"
		elif [ ${size} -eq 3 ]; then
			if [ "${COMP_WORDS[2]}" = "drop" ] ||
				[ "${COMP_WORDS[2]}" = "pop" ] ||
				[ "${COMP_WORDS[2]}" = "show" ]; then
			wordlist=$(ove_revtab_forall_parallel "git stash list" | \
				${ove_cmd2pathname["grep"]:?} -o 'OVE@[0-9].*' | \
				${ove_cmd2pathname["tr"]:?} '@' ' ' | \
				${ove_cmd2pathname["xargs"]:?} -n1 | \
				${ove_cmd2pathname["sort"]:?} -u)
			else
				return
			fi
		else
			return
		fi
	elif [ "${subcommand}" = "show" ]; then
		if [ ${size} -ge 2 ]; then
			# shellcheck disable=SC2016
			wordlist="$(ove_revtab_forall_parallel '${ove_cmd2pathname["git"]:?} tag') HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD CHERRY_PICK_HEAD"
			# shellcheck disable=SC2016
			wordlist+=" $(ove-list-heads | ${ove_cmd2pathname["awk"]:?} '{print $2}')"
			if [ -e ${OVE_OWEL_STATE_DIR}/revtab-news ]; then
				wordlist+=" $(${ove_cmd2pathname["grep"]:?} -o '^[a-f0-9]\+' ${OVE_OWEL_STATE_DIR}/revtab-news)"
			fi
			if [ -e ${OVE_OWEL_STATE_DIR}/revtab-ahead ]; then
				wordlist+=" $(${ove_cmd2pathname["grep"]:?} -o '^[a-f0-9]\+' ${OVE_OWEL_STATE_DIR}/revtab-ahead)"
			fi
		fi
	elif [ "${subcommand}" = "diff-owel" ] ||
		[ "${subcommand}" = "log-owel" ] ||
		[ "${subcommand}" = "revtab-diff" ] ||
		[ "${subcommand}" = "shortlog-owel" ]; then
		if [ ${size} -lt 4 ]; then
			wordlist=$(ove_list_tags_and_branches)
		else
			return
		fi
	elif [ "${subcommand}" = "do" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(ove_revtab_list_basename)
		elif [ ${size} -eq 3 ]; then
			if [ -d ${OVE_BASE_DIR}/${COMP_WORDS[2]} ]; then
				wordlist=$(${ove_cmd2pathname["find"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${OVE_BASE_DIR}/${COMP_WORDS[2]}) -perm -u=x -not -path '*.git*' -type f)
			fi
		elif [ ${size} -gt 3 ]; then
			return
		fi
	elif [ "${subcommand}" = "cd" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(ove_list_workspaces_base)
		elif [ ${size} -gt 2 ]; then
			return
		fi
	elif [ "${subcommand}" = "refresh" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_list_workspaces_base)
		fi
	elif [ "${subcommand}" = "vi" ] ||
		[ "${subcommand}" = "edit" ] ||
		[ "${subcommand}" = "emacs" ] ||
		[ "${subcommand}" = "gvim" ]; then
		if [ ${size} -lt 2 ]; then
			return
		fi
		refresh=0
		if [ -e ${OVE_OWEL_TMP_DIR}/ls-mod-files-base ]; then
			a=$(${ove_cmd2pathname["stat"]:?} --format '%Y' "${OVE_OWEL_TMP_DIR}/ls-mod-files-base")
			b=$(${ove_cmd2pathname["date"]:?} +%s)
			if [ $((b-a)) -gt $OVE_EDIT_LIFESPAN_TIME_IN_SEC ]; then
				refresh=1
			fi
		else
				refresh=1
		fi
		if [ $refresh -eq 1 ]; then
			ove-list-modified-files | \
				${ove_cmd2pathname["sed"]:?} -e "s,${OVE_BASE_DIR}/,,g" > ${OVE_OWEL_TMP_DIR}/ls-mod-files-base
		fi
		refresh=0
		if [ -e ${OVE_OWEL_TMP_DIR}/ls-files ]; then
			a=$(${ove_cmd2pathname["stat"]:?} --format '%Y' "${OVE_OWEL_TMP_DIR}/ls-files")
			b=$(${ove_cmd2pathname["date"]:?} +%s)
			if [ $((b-a)) -gt $OVE_EDIT_LIFESPAN_TIME_IN_SEC ]; then
				refresh=1
			fi
		else
				refresh=1
		fi
		if [ $refresh -eq 1 ]; then
			ove-ls-files > ${OVE_OWEL_TMP_DIR}/ls-files
		fi
		wordlist="$(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_TMP_DIR}/ls-mod-files-base ${OVE_OWEL_TMP_DIR}/ls-files)"
	elif [ "${subcommand}" = "add-config" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=${OVE_CONFIG_FILES_USER}
		elif [ ${size} -eq 3 ]; then
			wordlist="$(type ove_config_builtins_init | \
				${ove_cmd2pathname["grep"]:?} -o 'OVE_[A-Z_]\+')"
		fi
	elif [ "${subcommand}" = "config" ]; then
		# do we have a config file in the first place?
		if [ "$(ove_list_oveconfig_files_user)" != "" ]; then
			cmd="ove-config"
			if [ ${size} -eq 3 ]; then
				# is 2 a config file?
				if eval ove_config_validate_file ${COMP_WORDS[2]}; then
					# add the config file as argument to ove-config
					cmd+=" ${COMP_WORDS[2]}"
				else
					wordlist=$(ove_config_get_allowed ${COMP_WORDS[2]})
				fi
			elif [ ${size} -eq 4 ]; then
				wordlist=$(ove_config_get_allowed ${COMP_WORDS[3]})
			fi

			if [ "$wordlist" = "" ]; then
				# shellcheck disable=SC2016
				wordlist=$(eval ${cmd} | \
					${ove_cmd2pathname["sed"]:?} -e "s/\x1B\[[0-9;]*[mK]//g" -e "s|^/.*/\.oveconfig||g" -e "s|^:||" | \
					${ove_cmd2pathname["awk"]:?} '{print $1}')
			fi
		fi
	elif [ "${subcommand}" = "reset-hard" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_list_dirty_repos)
		fi
	elif [ "${subcommand}" = "add" ] ||
		[ "${subcommand}" = "diff" ] ||
		[ "${subcommand}" = "wdiff" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_list_dirty_repos_worktree)
		fi
	elif [ "${subcommand}" = "add" ] ||
		[ "${subcommand}" = "commit" ] ||
		[ "${subcommand}" = "diff" ] ||
		[ "${subcommand}" = "diff-cached" ] ||
		[ "${subcommand}" = "reset" ] ||
		[ "${subcommand}" = "wdiff" ] ||
		[ "${subcommand}" = "wdiff-cached" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_list_dirty_repos_index)
		fi
	elif [ "${subcommand}" = "branch" ] ||
		[ "${subcommand}" = "describe" ] ||
		[ "${subcommand}" = "fsck" ] ||
		[ "${subcommand}" = "heads2revtab" ] ||
		[ "${subcommand}" = "ls-remote" ] ||
		[ "${subcommand}" = "list-stash" ] ||
		[ "${subcommand}" = "readme" ] ||
		[ "${subcommand}" = "remote" ] ||
		[ "${subcommand}" = "show-dangling" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_revtab_list_basename)
		fi
	elif [ "${subcommand}" = "remove-repo" ] ||
		[ "${subcommand}" = "revtab-sync" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove_revtab_list_basename)
		fi
	elif [ "${subcommand}" = "list-repositories" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="behind ahead"
		fi
	elif [ "${subcommand}" = "news" ] ||
		[ "${subcommand}" = "behind" ] ||
		[ "${subcommand}" = "show-behind" ] ||
		[ "${subcommand}" = "show-news" ] ||
		[ "${subcommand}" = "pull" ]; then
		wordlist=$(ove_list_repositories "behind")
	elif [ "${subcommand}" = "ahead" ] ||
		[ "${subcommand}" = "rebase-autosquash" ] ||
		[ "${subcommand}" = "reset-ahead" ] ||
		[ "${subcommand}" = "show-ahead" ]; then
		wordlist=$(ove_list_repositories "ahead")
	elif [ "${subcommand}" = "demo" ] ||
		[ "${subcommand}" = "fetch" ] ||
		[ "${subcommand}" = "list-heads" ] ||
		[ "${subcommand}" = "patch-repo" ] ||
		[ "${subcommand}" = "status" ]; then
		wordlist=$(ove_revtab_list_basename)
	elif [ "${subcommand}" = "list-commands" ]; then
		wordlist=$(ove_list_command_categories)
	elif [ "${subcommand}" = "worktree" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="add"
			wordlist+=" list"
			wordlist+=" prune"
			wordlist+=" remove"
			wordlist+=" status"
		elif [ ${size} -ge 3 ]; then
			if [ "${COMP_WORDS[2]}" = "list" ] ||
				[ "${COMP_WORDS[2]}" = "remove" ] ||
				[ "${COMP_WORDS[2]}" = "status" ]; then
				wordlist=$(${ove_cmd2pathname["find"]:?} $OVE_OWEL_STATE_DIR/worktree/ -mindepth 1 -maxdepth 1 -type l 2> /dev/null)
				wordlist=${wordlist//$OVE_OWEL_STATE_DIR\/worktree\/}
			fi
		fi
	elif [ "${subcommand}" = "systest" ] ||
		[ "${subcommand}" = "systest-parallel" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(ove-list-systests)
		fi
	elif [ "${subcommand}" = "add-project" ]; then
		if [ ${size} -ge 4 ]; then
			wordlist="deps needs bootstrap configure build install clean test"
		fi
	elif [ "${subcommand}" = "apply" ]; then
		if [ ${size} -ge 2 ]; then
			return
		fi
	elif [ "${subcommand}" = "env" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist=$(compgen -A variable OVE_)
		else
			return
		fi
	elif [ "${subcommand}" = "task" ]; then
		if command -v task > /dev/null && [ ${size} -eq 2 ]; then
			wordlist=$(${ove_cmd2pathname["task"]:?} _commands)
		fi
	elif [ "${subcommand}" = "unittest" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(${ove_cmd2pathname["find"]:?} ${OVE_DIR}/tests -maxdepth 1 -mindepth 1 -name "t*.test" -type f -exec basename {} .test \;)
		fi
	elif [ "${subcommand}" = "what-is" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(${ove_cmd2pathname["find"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${PWD}) -maxdepth 1 -mindepth 1 -not -path '*.git' -type d -exec basename {} \;)
		fi
	elif [ "${subcommand}" = "head-tail" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(${ove_cmd2pathname["find"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${PWD}) -maxdepth 1 -mindepth 1 -not -path '*.git' -type f -exec basename {} \;)
		fi
	elif [ "${subcommand}" = "am" ] ||
		[ "${subcommand}" = "import" ]; then
		if [ ${size} -ge 2 ]; then
			wordlist=$(${ove_cmd2pathname["find"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${PWD}) -maxdepth 1 -mindepth 1 -name '*.tar.bz2' -not -path '*.git' -type f -exec basename {} \;)
		fi
	elif [ "${subcommand}" = "replicate" ]; then
		if [ ${size} -eq 2 ]; then
			if [ "$(type -t _known_hosts_real)" = "function" ]; then
				_known_hosts_real -a -- "$cur"
				return
			fi
		elif [ ${size} -eq 3 ] && [ "${COMP_WORDS[2]}" = "localhost" ]; then
			wordlist=$(ove_list_workspaces_full)
		elif [ ${size} -eq 3 ]; then
			wordlist=$(${ove_cmd2pathname["ssh"]:?} ${COMP_WORDS[2]} "command -v locate > /dev/null && locate .owel || find \${PWD} -maxdepth 2 -name .owel" | \
				${ove_cmd2pathname["sed"]:?} -e 's|/.owel$||g' | \
				${ove_cmd2pathname["xargs"]:?})
		elif [ ${size} -eq 4 ]; then
			wordlist="force save nofetch"
		elif [ ${size} -eq 5 ] && [ "${COMP_WORDS[4]}" = "force" ]; then
			wordlist="pull nofetch"
		fi
	elif [ "${subcommand}" = "replicate-cluster" ] ||
		[ "${subcommand}" = "replicate-cluster-parallel" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="force save nofetch"
		elif [ ${size} -eq 3 ] && [ "${COMP_WORDS[2]}" = "force" ]; then
			wordlist="pull"
		fi
	elif [ "${subcommand}" = "hooks" ]; then
		if [ ${size} -eq 2 ]; then
			wordlist="disable enable install list remove"
		elif [ ${size} -eq 3 ] && [ "${COMP_WORDS[2]}" = "install" ]; then
			if [ -d "${OVE_DIR}/hooks" ]; then
				wordlist=$(${ove_cmd2pathname["find"]:?} "${OVE_DIR}/hooks" -maxdepth 1 -mindepth 1 -type d -exec basename {} \;)
			fi
		elif [ ${size} -eq 3 ]; then
			if [ -d "${OVE_OWEL_DIR}/hooks" ]; then
				wordlist=$(${ove_cmd2pathname["find"]:?} "${OVE_OWEL_DIR}/hooks" -maxdepth 2 -mindepth 1 | \
					${ove_cmd2pathname["sed"]:?} -e "s,${OVE_OWEL_DIR}/hooks/,,g")
			fi
		fi
	elif [ "${subcommand}" = "tail-lastlog" ] ||
		[ "${subcommand}" = "less-lastlog" ]; then
		if [ ${size} -ge 2 ]; then
			if [ -d /var/tmp ]; then
				a="/var/tmp"
			else
				a="/tmp"
			fi

			# shellcheck disable=SC2015
			wordlist=$(${ove_cmd2pathname["find"]:?} ${a}/*/ove/logs -maxdepth 0 -type d | \
				${ove_cmd2pathname["rev"]:?} | \
				${ove_cmd2pathname["cut"]:?} -d'/' -f3 | \
				${ove_cmd2pathname["rev"]:?})
		else
			return
		fi
	elif [ "${subcommand}" = "lastlog-replay" ]; then
		if [ ${size} -ge 2 ]; then
			a=$(${ove_cmd2pathname["date"]:?} '+%Y%m%d')
			b=${a:0:4}
			# shellcheck disable=SC2016
			wordlist=$(ove-lastlog $a | ${ove_cmd2pathname["grep"]:?} -o "$b.*" | ${ove_cmd2pathname["awk"]:?} '{print $1}')
		fi
	fi

	if [ "${wordlist}" != "" ]; then
		mapfile -t COMPREPLY < <(compgen -W "${wordlist}" -- ${cur})
	else
		opts="${OVE_ALL_COMMANDS}"
		if compgen -W "${opts}" -- "${cur}" &> /dev/null; then
			mapfile -t COMPREPLY < <(compgen -W "${opts}" -- ${cur})
		fi
	fi
}

function ove_get_built_ins {
	local a

	a=$(${ove_cmd2pathname["grep"]:?} -o '^function ove-.* ' ${OVE_SELF} | \
		${ove_cmd2pathname["sed"]:?} -e ':a;N;$!ba;s/function ove-//g' | \
		LC_ALL="C"  ${ove_cmd2pathname["sort"]:?})
	a=${a//$'\n'/ }
	echo ${a}
}

function ove_update_tab_complete {
	local array
	local cmd
	local m
	local oldIFS

	# project commands
	OVE_ALL_COMMANDS=${OVE_PROJECT_COMMANDS}

	# built-in functions
	OVE_ALL_COMMANDS+=" ${OVE_BUILT_INS:?}"

	# scripts
	if [ "${OVE_SCRIPTS_LIST}" != "" ]; then
		OVE_ALL_COMMANDS+=" ${OVE_SCRIPTS_LIST}"
	fi

	# parallel project commands
	for cmd in ${OVE_PROJECT_COMMANDS}; do
		OVE_ALL_COMMANDS+=" ${cmd}-parallel"
	done

	for m in ${OVE_PROJECT_COMMANDS}; do
		if [[ $m != *clean ]]; then
			continue
		fi
		# clean/distclean/anyclean-me commands
		OVE_ALL_COMMANDS+=" ${m}me"
	done

	read -a array -r <<<"${OVE_ALL_COMMANDS}"
	oldIFS=${IFS}
	IFS=$'\n' OVE_ALL_COMMANDS=$(printf '%s ' $(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"${array[*]}"))
	# OVE_ALL_COMMANDS:space separated list of all OVE commands
	OVE_ALL_COMMANDS=${OVE_ALL_COMMANDS::-1}
	export OVE_ALL_COMMANDS
	IFS=${oldIFS}

	complete -o bashdefault -o default -F ove_bash_complete ove
	for cmd in ${OVE_PROJECT_COMMANDS}; do
		complete -W "${OVE_PROJECT_LIST}" "ove-${cmd}"
	done
}

function ove_add_script_helper {
	local a
	local b
	local c

	while IFS=: read -r a b c; do
		echo "$b:$c"
	done < "$1"
}

function ove_add_script_func {
	local htext
	local r_dir
	local s
	local s_dir

	s_dir=$1
	s=$2
	r_dir=${s_dir%\/*}
	r_dir=${r_dir%\/*}

	if [[ -v ove_scripts_name2path[${s}] ]]; then
		ove_echo_warning_noprefix "found script duplicate:"
		echo "$s_dir/$s (ignored)" 1>&2
		echo "${ove_scripts_name2path[${s}]}/$s" 1>&2
		return 1
	fi
	ove_scripts_name2path[${s}]=${s_dir}
	ove_scripts_paths[${s_dir}]=
	if [ -f ${s_dir}/${s}.help ]; then
		htext=$(<${s_dir}/${s}.help)
		if [[ "$htext" != *:PLUGIN ]]; then
			htext="$s:$(ove_add_script_helper ${s_dir}/${s}.help):PLUGIN"
		fi
	else
		htext="${s}: :run '${s_dir}/${s}':PLUGIN"
	fi

	eval "ove-${s}() {
		ove_entry || return
		local ove_plugin_helptext=\"${htext}\"
		local __scriptname=ove-${s}
		OVE_ACTIVE_REPO_DIR=${r_dir} \"${s_dir}\"/${s} \"\$@\"
	}"
	export -f ove-${s}
}

function ove_hooks_init {
	local _find
	local cmd
	local h
	local h_list
	local repo

	unset ove_hooks_post
	unset ove_hooks_pre
	declare -A -g ove_hooks_post
	declare -A -g ove_hooks_pre

	# project hooks
	if [ -d "${OVE_OWEL_DIR}/hooks" ]; then
		_find+="${OVE_OWEL_DIR}/hooks "
	fi

	# repo hooks
	for repo in $(ove_revtab_list_fullpath); do
		if ! [ -d "${repo}/.ove/hooks" ]; then
			continue
		fi

		_find+="${repo}/.ove/hooks "
	done

	# global hooks
	if [ -d "${OVE_GLOBAL_STATE_DIR}/hooks" ]; then
		_find+="${OVE_GLOBAL_STATE_DIR}/hooks "
	fi

	if [ "${_find}" != "" ]; then
		# post hooks
		h_list=$(${ove_cmd2pathname["find"]:?} -L ${_find} -name 'post-*' -perm -u=x -type f)
		for h in ${h_list}; do
			if ! [ -s "$h" ]; then
				continue
			fi
			cmd="${h##*/}"
			cmd=${cmd/post-/}
			ove_hooks_post[$cmd]+="$h "
		done

		# pre hooks
		h_list=$(${ove_cmd2pathname["find"]:?} -L ${_find} -name 'pre-*' -perm -u=x -type f)
		for h in ${h_list}; do
			if ! [ -s "$h" ]; then
				continue
			fi
			cmd="${h##*/}"
			cmd=${cmd/pre-/}
			ove_hooks_pre[$cmd]+="$h "
		done
	fi
}

function ove_scripts_init {
	local array
	local oldIFS
	local r_list
	local prev_scripts
	local repo
	local s
	local s_list

	unset ove_scripts_name2path
	unset ove_scripts_paths

	declare -A -g ove_scripts_name2path
	declare -A -g ove_scripts_paths

	OVE_SCRIPTS_LIST=

	# unset any ove- functions marked with "__scriptname"
	if prev_scripts=$(set | ${ove_cmd2pathname["grep"]:?} '^    local __scriptname=.*'); then
		prev_scripts=${prev_scripts//    local __scriptname=}
		prev_scripts=${prev_scripts//;}
		if [ "${prev_scripts}" != "" ]; then
			unset -f ${prev_scripts}
		fi
	fi

	# OWEL scripts
	if [ -d "${OVE_OWEL_DIR}/scripts" ]; then
		s_list=$(${ove_cmd2pathname["find"]:?} ${OVE_OWEL_DIR}/scripts -perm -u=x -not -name '*.help' -type f)
		for s in ${s_list}; do
			ove_add_script_func ${s%/*} ${s##*/}
			OVE_SCRIPTS_LIST+="${s##*/} "
		done
	fi

	# repo scripts
	for repo in $(ove_revtab_list_fullpath); do
		if [ ! -d "${repo}/.ove/scripts" ]; then
			continue
		fi
		r_list+="${repo}/.ove/scripts "
	done

	if [ "${r_list}" != "" ]; then
		s_list=$(${ove_cmd2pathname["find"]:?} -L ${r_list} -perm -u=x -not -name '*.help' -type f)
		for s in ${s_list}; do
			ove_add_script_func ${s%/*} ${s##*/}
			OVE_SCRIPTS_LIST+="${s##*/} "
		done
	fi

	read -a array -r <<<${OVE_SCRIPTS_LIST}
	oldIFS=${IFS}
	IFS=$'\n' OVE_SCRIPTS_LIST=$(printf '%s ' $(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"${array[*]}"))
	OVE_SCRIPTS_LIST=${OVE_SCRIPTS_LIST::-1}
	IFS=${oldIFS}
}

function ove_dirs_init {
	local s
	local s_link_name
	local t
	local t_link_name

	s_link_name="${OVE_BASE_DIR}/.ove.state"
	t_link_name="${OVE_BASE_DIR}/.ove.tmp"

	# OVE_GLOBAL_STATE_DIR:shared directory for all OVE workspaces (per user)
	OVE_GLOBAL_STATE_DIR=
	if [ -d /var/tmp ]; then
		OVE_GLOBAL_STATE_DIR=/var${OVE_TMP}
	else
		OVE_GLOBAL_STATE_DIR=${OVE_TMP}
	fi
	export OVE_GLOBAL_STATE_DIR

	# OVE_OWEL_STATE_DIR:state directory for one OVE workspace
	OVE_OWEL_STATE_DIR=
	if [ -h ${s_link_name} ]; then
		s="$(${ove_cmd2pathname["readlink"]:?} -f -- ${s_link_name})"
	fi

	if [ ! -h ${s_link_name} ] || [ "${s}" = "" ]; then
		if [ -h ${s_link_name} ]; then
			${ove_cmd2pathname["rm"]:?} ${s_link_name}
		fi
		OVE_OWEL_STATE_DIR=$(${ove_cmd2pathname["mktemp"]:?} -u -d -p ${OVE_GLOBAL_STATE_DIR}/${OVE_OWEL_NAME} state-XXXXXXXXXX)

		if ! ${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_STATE_DIR} 2> /dev/null; then
			OVE_OWEL_STATE_DIR=$(${ove_cmd2pathname["mktemp"]:?} -d)
		fi
		${ove_cmd2pathname["ln"]:?} -s ${OVE_OWEL_STATE_DIR} ${s_link_name}

		# always re-create tmp link
		if [ -h ${t_link_name} ]; then
			${ove_cmd2pathname["rm"]:?} ${t_link_name}
		fi
	else
		OVE_OWEL_STATE_DIR=${s}
		if [ ! -e "${s_link_name}" ]; then
			if ! ${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_STATE_DIR} 2> /dev/null; then
				OVE_OWEL_STATE_DIR=$(${ove_cmd2pathname["mktemp"]:?} -d)
			fi
		fi
	fi
	export OVE_OWEL_STATE_DIR

	if [ -h ${t_link_name} ]; then
		t="$(${ove_cmd2pathname["readlink"]:?} -f -- ${t_link_name})"
	fi

	# OVE_OWEL_TMP_DIR:temporary directory for one OVE workspace
	OVE_OWEL_TMP_DIR=
	if [ ! -h ${t_link_name} ] || [ "${t}" = "" ]; then
		if [ -h ${t_link_name} ]; then
			${ove_cmd2pathname["rm"]:?} ${t_link_name}
		fi
		# re-use last 10 characters from OVE_OWEL_STATE_DIR
		OVE_OWEL_TMP_DIR="${OVE_TMP}/${OVE_OWEL_NAME}/tmp-${OVE_OWEL_STATE_DIR: -10}"
		if ! ${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_TMP_DIR} 2> /dev/null; then
			OVE_OWEL_TMP_DIR=$(${ove_cmd2pathname["mktemp"]:?} -d)
		fi
		${ove_cmd2pathname["ln"]:?} -s ${OVE_OWEL_TMP_DIR} ${t_link_name}
	else
		OVE_OWEL_TMP_DIR=${t}
		if [ ! -e "${t_link_name}" ]; then
			if ! ${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_TMP_DIR} 2> /dev/null; then
				OVE_OWEL_TMP_DIR=$(${ove_cmd2pathname["mktemp"]:?} -d)
			fi
		fi
	fi
	export OVE_OWEL_TMP_DIR

	OVE_LOG_DIR="${OVE_GLOBAL_STATE_DIR}/logs"
	export OVE_LOG_DIR

	if [ ! -d "${OVE_LOG_DIR}" ]; then
		if ! ${ove_cmd2pathname["mkdir"]:?} -p "${OVE_LOG_DIR}" 2> /dev/null; then
			OVE_LOG_DIR=$(${ove_cmd2pathname["mktemp"]:?} -d -p ${OVE_GLOBAL_STATE_DIR})
		fi
	fi

	if [ ! -d "${OVE_GLOBAL_STATE_DIR}/.ove" ]; then
		if ! ${ove_cmd2pathname["mkdir"]:?} -p "${OVE_GLOBAL_STATE_DIR}/.ove" 2> /dev/null; then
			ove_echo_fatal_noprefix "could not create '${OVE_GLOBAL_STATE_DIR}/.ove'"
			return 1
		fi
	fi

	return 0
}

function ove_config_init {
	local f

	# cleanup previous configs
	if [ "${OVE_CONFIG_ALL}" != "" ]; then
		unset ${OVE_CONFIG_ALL} OVE_CONFIG_ALL
	fi

	# keep the order
	OVE_CONFIG_FILES_USER="${OVE_OWEL_DIR}/.oveconfig"
	OVE_CONFIG_FILES_USER+=" ${OVE_OWEL_STATE_DIR}/.oveconfig"
	OVE_CONFIG_FILES_USER+=" ${OVE_GLOBAL_STATE_DIR}/.oveconfig"
	OVE_CONFIG_FILES_USER+=" ${HOME}/.oveconfig"
	export OVE_CONFIG_FILES_USER

	OVE_CONFIG_FILE_PRIVATE="${OVE_GLOBAL_STATE_DIR}/.ove/.oveconfig.private"
	export OVE_CONFIG_FILE_PRIVATE

	OVE_CONFIG_FILES_ALL="${OVE_CONFIG_FILES_USER}"
	OVE_CONFIG_FILES_ALL+=" ${OVE_CONFIG_FILE_PRIVATE}"
	export OVE_CONFIG_FILES_ALL

	# first set any duplicates
	ove_read_config_pre $OVE_CONFIG_FILES_ALL

	# ...then read configs in order
	for f in ${OVE_CONFIG_FILES_ALL}; do
		if [ -e "${f}" ]; then
			ove_read_config ${f}
		fi
	done
}

function ove_config_builtins_init {
	# OVE_DRY_RUN:int:0|1:all-build-commands systest:dry-run
	if [ -z "${OVE_DRY_RUN+x}" ]; then
		export OVE_DRY_RUN=0
	fi

	# OVE_FETCH_MAX_PARALLEL:int:[0-9]+:fetch fetch-fetched fetch-remains:max number of 'git fetch' to run in parallel
	if [ -z "${OVE_FETCH_MAX_PARALLEL+x}" ]; then
		export OVE_FETCH_MAX_PARALLEL=0
	fi

	# OVE_FETCH_SUBMODULES:int:0-1:add-repo fetch:automatically run 'ove import-submodules' on inital clone
	if [ -z "${OVE_FETCH_SUBMODULES+x}" ]; then
		export OVE_FETCH_SUBMODULES=1
	fi

	# OVE_FETCH_EXCLUDE:string::fetch fetch-fetched fetch-remains:semi-colon separated list of repos to exclude
	if [ -z "${OVE_FETCH_EXCLUDE+x}" ]; then
		export OVE_FETCH_EXCLUDE=""
	fi

	# OVE_AUTO_CLONE:int:0|1:all-build-commands:automatically clone repos
	if [ -z "${OVE_AUTO_CLONE+x}" ]; then
		export OVE_AUTO_CLONE=0
	fi

	# OVE_CLONE_MAX_PARALLEL:int:[0-9]+:fetch:max number of 'git clone' to run in parallel
	if [ -z "${OVE_CLONE_MAX_PARALLEL+x}" ]; then
		export OVE_CLONE_MAX_PARALLEL=0
	fi

	# OVE_CLONE_RETRY:int:[0-9]+:fetch:number of retry attempts for 'git clone'
	if [ -z "${OVE_CLONE_RETRY+x}" ]; then
		export OVE_CLONE_RETRY=1
	fi

	# OVE_CLONE_RETRY_PERIOD:int:[0-9]+:fetch:sleep period between every clone attempt, 0 = no sleep, <0 randomize sleep
	if [ -z "${OVE_CLONE_RETRY_PERIOD+x}" ]; then
		export OVE_CLONE_RETRY_PERIOD=1
	fi

	# OVE_LOCATE_SEARCH_DIR:string::locate:where to search for OVE workspaces (only if 'locate' is unavailable)
	if [ -z "${OVE_LOCATE_SEARCH_DIR+x}" ]; then
		OVE_LOCATE_SEARCH_DIR=$(${ove_cmd2pathname["readlink"]:?} -f -- $(${ove_cmd2pathname["dirname"]:?} ${HOME}))
		export OVE_LOCATE_SEARCH_DIR
	fi

	# OVE_DEFAULT_BRANCH_NAME:string::add-repo unittest:default branch name
	if [ -z "${OVE_DEFAULT_BRANCH_NAME+x}" ]; then
		export OVE_DEFAULT_BRANCH_NAME="main"
	fi

	# OVE_OWEL_CI_BRANCH:string::log:branch to use for 'ove log'
	if [ -z "${OVE_OWEL_CI_BRANCH+x}" ]; then
		export OVE_OWEL_CI_BRANCH="origin/${OVE_DEFAULT_BRANCH_NAME}"
	fi

	# OVE_LOGLEVEL:int:0-10:all loglevel:set a specific log level
	if [ -z "${OVE_LOGLEVEL+x}" ]; then
		export OVE_LOGLEVEL=1
		export OVE_REDIRECT_OUTPUT=""
	fi

	# OVE_TRACE_MODE:int:0|1:all loglevel:what to include in the trace, skip OVE internals (=0), include OVE internals (=1)
	if [ -z "${OVE_TRACE_MODE+x}" ]; then
		export OVE_TRACE_MODE=0
	fi

	# OVE_TRACE_GRAPH_VIEWER:string::loglevel 6:semi-colon separated list of extension-colon-viewer pairs
	if [ -z "${OVE_TRACE_GRAPH_VIEWER+x}" ]; then
		export OVE_TRACE_GRAPH_VIEWER=
	fi

	# OVE_AUTO_CORRECT:int:0|1:all:automatically correct commands
	if [ -z "${OVE_AUTO_CORRECT+x}" ]; then
		export OVE_AUTO_CORRECT=0
	fi

	# OVE_LOCAL_ECHO:int:0-2:all:print command-to-be-executed on stderr, no echo (=0), echo (=1) or colored echo (=2)
	if [ -z "${OVE_LOCAL_ECHO+x}" ]; then
		export OVE_LOCAL_ECHO=0
	fi

	# OVE_AUTO_RM_LOGS:int:0|days:all:automatically remove OVE logs
	if [ -z "${OVE_AUTO_RM_LOGS+x}" ]; then
		export OVE_AUTO_RM_LOGS=0
	fi

	# OVE_IMPORT_PROJECTS:int:0-2:add-repo:skip (=0), import (=1) or prompt user (=2)
	if [ -z "${OVE_IMPORT_PROJECTS+x}" ]; then
		export OVE_IMPORT_PROJECTS=2
	fi

	# OVE_ANONYMIZE_LOGS:int:0|1:all:try to anonymize logs by removing user specific info
	if [ -z "${OVE_ANONYMIZE_LOGS+x}" ]; then
		export OVE_ANONYMIZE_LOGS=0
	fi

	# OVE_REVTAB_CHECK:int:0|1:all:keep repos in-sync with 'revtab'
	if [ -z "${OVE_REVTAB_CHECK+x}" ]; then
		export OVE_REVTAB_CHECK=1
	fi

	# OVE_PATCH_REPOS:int:0|1:patch-repo pull source:if set, use OVE_PATCH_REPOS_METHOD to apply patches
	if [ -z "${OVE_PATCH_REPOS+x}" ]; then
		export OVE_PATCH_REPOS=1
	fi

	# OVE_PATCH_REPOS_METHOD:string:am|apply|auto:patch-repo pull source:patch method
	if [ -z "${OVE_PATCH_REPOS_METHOD+x}" ]; then
		export OVE_PATCH_REPOS_METHOD="apply"
	fi

	# OVE_MAKEFLAGS:int::all-build-commands:passed on to 'make' based build systems through MAKEFLAGS
	if [ -z "${OVE_MAKEFLAGS+x}" ]; then
		OVE_MAKEFLAGS="-j$(${ove_cmd2pathname["getconf"]:?} _NPROCESSORS_ONLN)"
		export OVE_MAKEFLAGS
	fi

	# OVE_LOG_DIR_DISK_USAGE_WARNING_MB:int:[0-9]+:all:threshold when logs take too much space
	if [ -z "${OVE_LOG_DIR_DISK_USAGE_WARNING_MB+x}" ]; then
		export OVE_LOG_DIR_DISK_USAGE_WARNING_MB=100
	fi

	# OVE_TAINT_USER_ENV:int:0|1:user's env:taint user's PATH/LD_LIBRARY_PATH/PKG_CONFIG/MAKEFLAGS
	if [ -z "${OVE_TAINT_USER_ENV+x}" ]; then
		export OVE_TAINT_USER_ENV=1
	fi

	# OVE_BUILDME_PRE_STEPS:string::buildme buildme-parallel:project step(s) to run without build order considerations
	if [ -z "${OVE_BUILDME_PRE_STEPS+x}" ]; then
		export OVE_BUILDME_PRE_STEPS="bootstrap"
	fi

	# OVE_BUILDME_STEPS:string::buildme buildme-parallel:project step(s) to run
	if [ -z "${OVE_BUILDME_STEPS+x}" ]; then
		export OVE_BUILDME_STEPS="configure build install"
	fi

	# OVE_SYSTEST_REPEAT:int:>0:systest:repeat tests
	if [ -z "${OVE_SYSTEST_REPEAT+x}" ]; then
		export OVE_SYSTEST_REPEAT=1
	fi

	# OVE_SYSTEST_SKIP:int|string::systest:skip every nth test or specific tests
	if [ -z "${OVE_SYSTEST_SKIP+x}" ]; then
		export OVE_SYSTEST_SKIP=1
	fi

	# OVE_SYSTEST_CLEANUP:int:0|1:systest:cleanup child procs after each systest
	if [ -z "${OVE_SYSTEST_CLEANUP+x}" ]; then
		export OVE_SYSTEST_CLEANUP=0
	fi

	# OVE_SYSTEST_HEADER:string:detailed|short|off:systest:systest text detail level
	if [ -z "${OVE_SYSTEST_HEADER+x}" ]; then
		export OVE_SYSTEST_HEADER="short"
	fi

	# OVE_FORCE_SERIALIZE_COMMANDS:string::all-parallel-build-commands:force OVE to serialize one or more project steps
	if [ -z "${OVE_FORCE_SERIALIZE_COMMANDS+x}" ]; then
		export OVE_FORCE_SERIALIZE_COMMANDS=""
	fi

	# OVE_LOOP_INOTIFY_EXTRA:string::loop:semi-colon separated list of additional files/directories to watch using inotify
	if [ -z "${OVE_LOOP_INOTIFY_EXTRA+x}" ]; then
		export OVE_LOOP_INOTIFY_EXTRA=""
	fi

	# OVE_TMUX_LAYOUT:string::less-lastlog loop run tail-lastlog:tmux layout to use when launching new panes
	if [ -z "${OVE_TMUX_LAYOUT+x}" ]; then
		export OVE_TMUX_LAYOUT="tiled"
	fi

	# OVE_TMUX_PANE_HEADER:string:wide|short|off:fzf loop run :header style for tmux panes
	if [ -z "${OVE_TMUX_PANE_HEADER+x}" ]; then
		export OVE_TMUX_PANE_HEADER="short"
	fi

	# OVE_TMUX_PANE_PER_WINDOW:int::run run-parallel:max number of tmux panes within one tmux window, no limit (=0)
	if [ -z "${OVE_TMUX_PANE_PER_WINDOW+x}" ]; then
		export OVE_TMUX_PANE_PER_WINDOW=0
	fi

	# OVE_LOCATE_LIFESPAN_TIME_IN_SEC:int::cd forowel locate locate-all refresh:local OVE workspace cache lifespan
	if [ -z "${OVE_LOCATE_LIFESPAN_TIME_IN_SEC+x}" ]; then
		export OVE_LOCATE_LIFESPAN_TIME_IN_SEC=86400
	fi

	# OVE_EDIT_LIFESPAN_TIME_IN_SEC:int::emacs vi:cache ls-files and ls-modified-files
	if [ -z "${OVE_EDIT_LIFESPAN_TIME_IN_SEC+x}" ]; then
		export OVE_EDIT_LIFESPAN_TIME_IN_SEC=30
	fi

	# OVE_IDE_LOOP_ARGS:string::ide:semi-colon separated list of arguments to 'ove-loop' to launch
	if [ -z "${OVE_IDE_LOOP_ARGS+x}" ]; then
		export OVE_IDE_LOOP_ARGS="3600 0 0 fetch;60 1 0 ahead;3600 0 0 news"
	fi

	# OVE_IDE_SLEEP_BETWEEN_COMMANDS:float::ide:sleep between each command
	if [ -z "${OVE_IDE_SLEEP_BETWEEN_COMMANDS+x}" ]; then
		export OVE_IDE_SLEEP_BETWEEN_COMMANDS=0.5
	fi

	# OVE_ACCELERATE_BUILDS:int:0|1:all-build-commands:prefix build acceleration tools (ccache/icecream) to PATH
	if [ -z "${OVE_ACCELERATE_BUILDS+x}" ]; then
		export OVE_ACCELERATE_BUILDS=0
	fi

	# OVE_STATUS_TRUNC:int:0|1:status:truncate output to fit terminal
	if [ -z "${OVE_STATUS_TRUNC+x}" ]; then
		export OVE_STATUS_TRUNC=1
	fi

	# OVE_STATUS_TRUNC_REVISION:int::status:truncate (>0) revision column, no truncation (=0)
	if [ -z "${OVE_STATUS_TRUNC_REVISION+x}" ]; then
		export OVE_STATUS_TRUNC_REVISION=0
	fi

	# OVE_INSTALL_PKG:int:0-2:buildme buildme-parallel install-pkg install-pkg-os:skip (=0), install (=1) or prompt user (=2) packages
	if [ -z "${OVE_INSTALL_PKG+x}" ]; then
		export OVE_INSTALL_PKG=2
	fi

	# OVE_INSTALL_PKG_ELEVATE_METHOD:string:sudo|su:install-pkg install-pkg-os:elevating method to use when installing packages
	if [ -z "${OVE_INSTALL_PKG_ELEVATE_METHOD+x}" ]; then
		export OVE_INSTALL_PKG_ELEVATE_METHOD="sudo"
	fi

	# OVE_GIT_COMMAND_OPTIONS_DEFAULT:string::all commands:semi-colon separated list of git command options (defaults)
	if [ -z "${OVE_GIT_COMMAND_OPTIONS_DEFAULT+x}" ]; then
		OVE_GIT_COMMAND_OPTIONS_DEFAULT=
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@add:-p;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@branch:-vv --color=always;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@checkout:-p;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@clean:-dffx;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@clone: ;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@describe:--tags --always --dirty --long;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@diff:--color=always;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@fetch:--all --tags;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@fsck:--full;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@grep:--color=always;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@reset:-p;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@pull:--rebase;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@show:--first-parent --color=always;"
		OVE_GIT_COMMAND_OPTIONS_DEFAULT+=".*@status:-bs -uno;"
		export OVE_GIT_COMMAND_OPTIONS_DEFAULT
	fi

	# OVE_GIT_COMMAND_OPTIONS_OVERRIDE:string::all commands:semi-colon separated list of git command options (overrides)
	if [ -z "${OVE_GIT_COMMAND_OPTIONS_OVERRIDE+x}" ]; then
		export OVE_GIT_COMMAND_OPTIONS_OVERRIDE=
	fi

	# OVE_GIT_USE_FLOCK:int::all commands:use flock to serialize multiple git commands within one repository
	if [ -z "${OVE_GIT_USE_FLOCK+x}" ]; then
		export OVE_GIT_USE_FLOCK=1
	fi

	# OVE_ALIAS:int:0|1::enable/disable aliases defined in OVE_ALIAS_LIST
	if [ -z "${OVE_ALIAS+x}" ]; then
		export OVE_ALIAS=0
	fi

	# OVE_ALIAS_LIST:string:::semi-colon separated list of shell aliases
	if [ -z "${OVE_ALIAS_LIST+x}" ]; then
		export OVE_ALIAS_LIST="a=ove-ahead;b=ove-behind;d=ove-diff;f=ove-fetch;ff=ove-fetch-fetched;h=ove-list-aliases;n=ove-news;s=ove-status;sa=ove-show-ahead;sb=ove-show-behind;sn=ove-show-news"
	fi

	# OVE_DEMO_DIVISOR:int::demo:divisor sent to 'lastlog-replay' and later to 'scriptreplay'
	if [ -z "${OVE_DEMO_DIVISOR+x}" ]; then
		export OVE_DEMO_DIVISOR=20
	fi

	# OVE_BATCH_IT:int:0-1:all:run commands using ts/tsp batch system
	if [ -z "${OVE_BATCH_IT+x}" ]; then
		export OVE_BATCH_IT=0
	fi

	# OVE_RECORD_IT:int:0-1:all:screen record commands
	if [ -z "${OVE_RECORD_IT+x}" ]; then
		export OVE_RECORD_IT=0
	fi

	# OVE_COMMAND_SETSID:int:0-1:all:run non-terminal commands in a separate session (SID)
	if [ -z "${OVE_COMMAND_SETSID+x}" ]; then
		export OVE_COMMAND_SETSID=0
	fi

	# OVE_HASH_SIZE_THRESHOLD_IN_BYTES:int::all:do not run md5sum on large files
	if [ -z "${OVE_HASH_SIZE_THRESHOLD_IN_BYTES+x}" ]; then
		export OVE_HASH_SIZE_THRESHOLD_IN_BYTES="104857600"
	fi

	# OVE_DISTROCHECK_STEPS:string:ove running ssh ssh_config stopped user verbose worktree X:distrocheck distrocheck-parallel:list of steps to perform for distrocheck
	if [ -z "${OVE_DISTROCHECK_STEPS+x}" ]; then
		export OVE_DISTROCHECK_STEPS=""
	fi

	# OVE_DISTROCHECK_CONTAINER_NAME:string::distrocheck distrocheck-parallel:set container name
	if [ -z "${OVE_DISTROCHECK_CONTAINER_NAME+x}" ]; then
		export OVE_DISTROCHECK_CONTAINER_NAME=""
	fi

	# OVE_DISTROCHECK_CONTAINER_PREFIX:string::distrocheck distrocheck-parallel:prefix container name
	if [ -z "${OVE_DISTROCHECK_CONTAINER_PREFIX+x}" ]; then
		export OVE_DISTROCHECK_CONTAINER_PREFIX=""
	fi

	# OVE_DISTROCHECK_LAUNCH_EXTRA_ARGS:string::distrocheck distrocheck-parallel:extra args sent to container framework on launch
	if [ -z "${OVE_DISTROCHECK_LAUNCH_EXTRA_ARGS+x}" ]; then
		export OVE_DISTROCHECK_LAUNCH_EXTRA_ARGS=""
	fi

	# OVE_HOOKS_APPEND_TO_LASTLOG:int:0-1:all:append output from hooks to lastlog
	if [ -z "${OVE_HOOKS_APPEND_TO_LASTLOG+x}" ]; then
		export OVE_HOOKS_APPEND_TO_LASTLOG=1
	fi

	# OVE_REFRESH_STEPS:string::refresh:steps to perform for refresh
	if [ -z "${OVE_REFRESH_STEPS+x}" ]; then
		export OVE_REFRESH_STEPS=interactive
	fi

	# OVE_HEADS2REVTAB_MODE:int:0|1:heads2revtab:include detached repos (=0), exclude detached repos (=1)
	if [ -z "${OVE_HEADS2REVTAB_MODE+x}" ]; then
		export OVE_HEADS2REVTAB_MODE=0
	fi

	# OVE_PROJECT_DISABLE:string::all-build-commands:disable specified projects (regex)
	if [ -z "${OVE_PROJECT_DISABLE+x}" ]; then
		export OVE_PROJECT_DISABLE=""
	fi

	# OVE_AUTO_INSTALL_INCUS:int:0|1:all:automatically install incus on this host
	if [ -z "${OVE_AUTO_INSTALL_INCUS+x}" ]; then
		export OVE_AUTO_INSTALL_INCUS=0
	fi

	# OVE_HUB_URL_LIST:string::list-hub refresh-hub setup:semi-colon separated list of hub URLs
	if [ -z "${OVE_HUB_URL_LIST+x}" ]; then
		export OVE_HUB_URL_LIST=
	fi
}

# $1: a built in OVE config
function ove_config_get_allowed {
	if [ $# -ne 1 ]; then
		return
	elif [ ! -s ${OVE_DIR}/doc/ove-config-list.md ]; then
		return
	elif ! ${ove_cmd2pathname["grep"]:?} -q "^| $1 " ${OVE_DIR}/doc/ove-config-list.md; then
		return
	fi

	# shellcheck disable=SC2016
	${ove_cmd2pathname["grep"]:?} "^| $1 " ${OVE_DIR}/doc/ove-config-list.md | \
		${ove_cmd2pathname["awk"]:?} '{print $6}' | \
		${ove_cmd2pathname["sed"]:?} -e 's,\\|, ,g' -e 's,|,,g'
}

# re-initialize
function ove_reinit {
	if ! ove_init; then
		return 1
	fi

	ove_post_checks

	return 0
}

# probe a few external programs and their capabilities
function ove_externals_probe {
	if [ -z "${OVE_COLUMN_WRAP_BUG}" ]; then
		if ! ( for i in {1..205} ; do echo -n 123456789, ; done ; echo ) | ${ove_cmd2pathname["column"]:?} -t -s "," &> /dev/null; then
			OVE_COLUMN_WRAP_BUG=1
		else
			OVE_COLUMN_WRAP_BUG=0
		fi
		ove_update_config "${OVE_CONFIG_FILE_PRIVATE:?}" "OVE_COLUMN_WRAP_BUG" "$OVE_COLUMN_WRAP_BUG"
	fi
	export OVE_COLUMN_WRAP_BUG

	if [ -z "${OVE_LESS_MORE_OPTIONS}" ]; then
		if ${ove_cmd2pathname["less"]:?} --version |& ${ove_cmd2pathname["head"]:?} -1 | ${ove_cmd2pathname["grep"]:?} -q '^less [0-9]\+'; then
			OVE_LESS_MORE_OPTIONS=1
		else
			OVE_LESS_MORE_OPTIONS=0
		fi
		ove_update_config "${OVE_CONFIG_FILE_PRIVATE:?}" "OVE_LESS_MORE_OPTIONS" "$OVE_LESS_MORE_OPTIONS"
	fi
	export OVE_LESS_MORE_OPTIONS

	if [ -z "${OVE_SCRIPT_OPTIONS}" ]; then
		OVE_SCRIPT_OPTIONS="-q "
		script_help=$(2>&1 ${ove_cmd2pathname["script"]:?} --help)
		if [[ "${script_help}" != *"invalid option"* ]]; then
			if [[ "${script_help}" == *"-a"* ]]; then
				OVE_SCRIPT_OPTIONS+="-a "
			fi
			if [[ "${script_help}" == *"-e"* ]]; then
				OVE_SCRIPT_OPTIONS+="-e "
			fi
			if [[ "${script_help}" == *"-f"* ]]; then
				OVE_SCRIPT_OPTIONS+="-f "
			fi
		fi
		OVE_SCRIPT_OPTIONS="${OVE_SCRIPT_OPTIONS% *}"
		ove_update_config "${OVE_CONFIG_FILE_PRIVATE:?}" "OVE_SCRIPT_OPTIONS" "$OVE_SCRIPT_OPTIONS"
	fi
	export OVE_SCRIPT_OPTIONS

	if [ -z "${OVE_FLOCK_OPTIONS}" ]; then
		if ${ove_cmd2pathname["flock"]:?} --help |& ${ove_cmd2pathname["grep"]:?} -q '\--no-fork'; then
			OVE_FLOCK_OPTIONS="--no-fork"
		fi
		ove_update_config "${OVE_CONFIG_FILE_PRIVATE:?}" "OVE_FLOCK_OPTIONS" "$OVE_FLOCK_OPTIONS"
	fi
	export OVE_FLOCK_OPTIONS
}

function ove_trace_barrier {
	local s="${SECONDS}"

	echo "${BASHPID}" > "${OVE_OWEL_TMP_DIR}"/bash.pid
	while true; do
		if [ -e "${OVE_OWEL_TMP_DIR}"/trace.cont ]; then
			break
		elif [ $((SECONDS - s)) -gt 5 ]; then
			break
		fi
	done

	if [ ! -e "${OVE_OWEL_TMP_DIR}"/trace.cont ]; then
		return 1
	fi

	read -r s < "${OVE_OWEL_TMP_DIR}"/trace.cont
	if [ "$s" -eq 0 ]; then
		return 1
	fi

	return 0
}

function ove_time_init {
	if [ "${EPOCHREALTIME}" != "" ]; then
		OVE_TIME_SEPARATOR=${EPOCHREALTIME//[0-9]}
		OVE_TIME_GRANULARITY=6
	else
		OVE_TIME_SEPARATOR=","
		OVE_TIME_GRANULARITY=9
	fi
	export OVE_TIME_SEPARATOR
	export OVE_TIME_GRANULARITY
}

# init:initialize OVE workspace
function ove_init {
	local dir
	local func
	local resolved
	local script_help

	if [ -n "${OVE_TRACE_CMD+x}" ] && [ "${OVE_TRACE_MODE}" -eq 1 ]; then
		if ! ove_trace_barrier; then
			return 1
		fi
	fi

	if ! dir=$(ove_get_base_dir); then
		return 1
	fi

	# OVE_BASE_DIR:OVE workspace base directory
	OVE_BASE_DIR="${dir}"
	export OVE_BASE_DIR

	# OVE_OWEL_DIR:OWEL base dir. This directory contains 'projs', 'revtab', projects/... files.
	OVE_OWEL_DIR=$(${ove_cmd2pathname["readlink"]:?} -f -- ${OVE_BASE_DIR}/.owel)
	export OVE_OWEL_DIR

	# OVE_OWEL_NAME:OWEL name
	OVE_OWEL_NAME=${OVE_OWEL_DIR##*/}
	export OVE_OWEL_NAME

	# OVE_PROJECT_LIST:space separated list of OVE projects defined in 'projs'
	OVE_PROJECT_LIST=$(ove_list_projects)
	export OVE_PROJECT_LIST

	# OVE_PROJECT_COMMANDS:space separated list of project commands
	OVE_PROJECT_COMMANDS=$(ove_project_commands_list)
	export OVE_PROJECT_COMMANDS

	# OVE_STAGE_DIR:directory where intermediate build files can be shared
	OVE_STAGE_DIR=${OVE_BASE_DIR}/stage
	export OVE_STAGE_DIR

	# OVE_ARCHIVE_DIR:directory to share build archive files
	OVE_ARCHIVE_DIR=${OVE_BASE_DIR}/archives
	export OVE_ARCHIVE_DIR

	resolved="$(${ove_cmd2pathname["readlink"]:?} -f -- ${OVE_BASE_DIR}/ove)"
	# OVE_DIR:OVE source code directory
	if ! OVE_DIR="$(cd "${resolved%/*}" || exit 1; pwd -P)"; then
		return 1
	fi
	export OVE_DIR

	OVE_BASENAME="${resolved##*/}"
	export OVE_BASENAME

	OVE_SELF="${OVE_DIR}/${OVE_BASENAME}"
	export OVE_SELF

	: "${OVE_PREFIX:=/usr}"
	export OVE_PREFIX

	if ! ove_dirs_init; then
		return 1
	fi
	ove_config_init
	if ! ove_revtab_init; then
		return 1
	fi
	if ! ove_projects_init; then
		return 1
	fi
	ove_scripts_init

	ove_hooks_init

	ove_sanitise_vars

	if [ "${OVE_LOGLEVEL}" = "2" ]; then
		set -x
	fi

	if [ -s "${OVE_DIR}"/ove.static ]; then
		source "${OVE_DIR}"/ove.static
	fi

	# remove broken README symlink
	if [ -L "${OVE_BASE_DIR}"/README ] && [ ! -e "${OVE_BASE_DIR}"/README ]; then
		${ove_cmd2pathname["rm"]:?} "${OVE_BASE_DIR}"/README
	fi

	if [ ! -L "${OVE_BASE_DIR}"/README ]; then
		if [ -s "${OVE_OWEL_DIR}"/README ]; then
			( cd "${OVE_BASE_DIR}" && ${ove_cmd2pathname["ln"]:?} -s "${OVE_OWEL_DIR}"/README .)
		elif [ -s "${OVE_OWEL_DIR}"/README.md ]; then
			( cd "${OVE_BASE_DIR}" && ${ove_cmd2pathname["ln"]:?} -s "${OVE_OWEL_DIR}"/README.md README )
		fi
	fi

	ove_update_tab_complete

	ove_config_builtins_init

	if [[ "${OVE_OS_KERNEL,,}" != *bsd* ]]; then
		read -r -a OVE_LD_SEARCH_PATH < <(${ove_cmd2pathname["ld"]:?} --verbose 2> /dev/null | \
		${ove_cmd2pathname["sed"]:?} -n -e '/^SEARCH_DIR/s,SEARCH_DIR("=\?,,g' -e 's,");,,gp')
	else
		read -r -a OVE_LD_SEARCH_PATH < <(${ove_cmd2pathname["gcc"]:?} -Xlinker --verbose  2>/dev/null | sed -n -e '/^SEARCH_DIR/s,SEARCH_DIR("=,,g' -e 's,");,,gp')
	fi
	OVE_LDFLAGS=""
	for dir in "${OVE_LD_SEARCH_PATH[@]}"; do
		OVE_LDFLAGS+=" -L${OVE_STAGE_DIR}${dir}"
	done
	for dir in "${OVE_LD_SEARCH_PATH[@]}"; do
		OVE_LDFLAGS+=" -Wl,-rpath-link=${OVE_STAGE_DIR}${dir}"
	done
	export OVE_LDFLAGS

	OVE_CPPFLAGS=" -I${OVE_STAGE_DIR}${OVE_PREFIX}/include"
	export OVE_CPPFLAGS

	# OVE_SHA:OVE version in use
	OVE_SHA=$(${ove_cmd2pathname["git"]:?} -C ${OVE_DIR} rev-parse --short HEAD)
	export OVE_SHA

	# OVE_LAST_COMMAND:file of the last OVE command executed
	OVE_LAST_COMMAND=
	export OVE_LAST_COMMAND

	OVE_PAGER="${ove_cmd2pathname["less"]:?} -R"
	export OVE_PAGER

	OVE_PKG_CONFIG_PATH="${OVE_STAGE_DIR}${OVE_PREFIX}/lib/pkgconfig:"
	OVE_LD_LIBRARY_PATH=""
	for dir in "${OVE_LD_SEARCH_PATH[@]}"; do
		OVE_LD_LIBRARY_PATH+="${OVE_STAGE_DIR}${dir}:"
	done
	unset OVE_LD_SEARCH_PATH

	if ove_debian_based; then
		OVE_LD_LIBRARY_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib/x86_64-linux-gnu:"
		OVE_LD_LIBRARY_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib"
		OVE_PKG_CONFIG_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib/x86_64-linux-gnu/pkgconfig"
	else
		OVE_LD_LIBRARY_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib:"
		OVE_LD_LIBRARY_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib64"
		OVE_PKG_CONFIG_PATH+="${OVE_STAGE_DIR}${OVE_PREFIX}/lib64/pkgconfig"
	fi
	export OVE_LD_LIBRARY_PATH
	export OVE_PKG_CONFIG_PATH

	if [ ${OVE_TAINT_USER_ENV} -eq 1 ]; then
		if [[ ${PATH} != *"${OVE_STAGE_DIR}"* ]]; then
			PATH=${OVE_STAGE_DIR}${OVE_PREFIX}/sbin:${OVE_STAGE_DIR}${OVE_PREFIX}/bin:${PATH}
		fi

		if [ ${OVE_ACCELERATE_BUILDS} -eq 1 ]; then
			# icecream
			dir="/usr/lib/icecc/bin"
			if command -v icecc > /dev/null && \
				[ -d "${dir}" ] && \
				[[ ${PATH} != *${dir}* ]]; then
				PATH=${dir}:${PATH}
			fi

			# ccache
			if command -v ccache > /dev/null && \
				[[ ${PATH} != *ccache* ]]; then
				if ove_debian_based; then
					dir="/usr/lib/ccache"
				else
					dir="/usr/lib64/ccache"
				fi

				if [ -d ${dir} ]; then
					PATH=${dir}:${PATH}
				fi
			fi
		fi
		export PATH

		if [ -n "${LD_LIBRARY_PATH}" ] && [[ ${LD_LIBRARY_PATH} != *"${OVE_LD_LIBRARY_PATH}"* ]]; then
			LD_LIBRARY_PATH=${OVE_LD_LIBRARY_PATH}:${LD_LIBRARY_PATH}
		else
			LD_LIBRARY_PATH=${OVE_LD_LIBRARY_PATH}
		fi
		export LD_LIBRARY_PATH

		if [ -n "${PKG_CONFIG_PATH}" ] && [[ ${PKG_CONFIG_PATH} != *"${OVE_PKG_CONFIG_PATH}"* ]]; then
			PKG_CONFIG_PATH=${OVE_PKG_CONFIG_PATH}:${PKG_CONFIG_PATH}
		else
			PKG_CONFIG_PATH=${OVE_PKG_CONFIG_PATH}
		fi
		export PKG_CONFIG_PATH

		MAKEFLAGS="${OVE_MAKEFLAGS}"
		export MAKEFLAGS
	else
		ove_unsource_user_env
	fi

	ove_externals_probe

	if [ $(ove_repos_fetched) -eq $(${ove_cmd2pathname["wc"]:?} -w <<<"${OVE_REPO_LIST}") ]; then
		unset OVE_PROJECT_LIST_BUILDABLE
	else
		ove_buildable_projects
	fi

	ove_update_checksum

	# export functions
	for func in $(compgen -A function | ${ove_cmd2pathname["grep"]:?} "^ove[-_]") ove; do
		# shellcheck disable=SC2163
		export -f ${func}
	done

	# setup git command options
	ove_git_command_options_init

	# time
	ove_time_init

	# keep this last
	if [ -n "${OVE_TRACE_CMD+x}" ] && [ "${OVE_TRACE_MODE}" -eq 0 ]; then
		if ! ove_trace_barrier; then
			return 1
		fi
	fi

	return 0
}

function ove_disk_usage_check {
	local log_dir_disk_usage

	# log dir disk usage
	if [ ${OVE_LOG_DIR_DISK_USAGE_WARNING_MB} -ne 0 ]; then
		log_dir_disk_usage=$(${ove_cmd2pathname["du"]:?} -B 1M -s ${OVE_LOG_DIR})
		log_dir_disk_usage=${log_dir_disk_usage%%$'\t'*}
		if [ $log_dir_disk_usage -ge ${OVE_LOG_DIR_DISK_USAGE_WARNING_MB} ]; then
			echo
			ove_echo_note_noprefix "the directory '${OVE_LOG_DIR}' is ${log_dir_disk_usage}MB, you might want to:"
			echo
			echo "- remove OVE logs older than X days:"
			echo -e "\tove rm-logs X"
			echo "- automatically remove OVE logs older than X days:"
			echo -e "\tove add-config ${OVE_GLOBAL_STATE_DIR}/.oveconfig OVE_AUTO_RM_LOGS X"
			echo "- increase the threshold (=${OVE_LOG_DIR_DISK_USAGE_WARNING_MB}MB) for this NOTE 10x times:"
			echo -e "\tove add-config ${OVE_GLOBAL_STATE_DIR}/.oveconfig OVE_LOG_DIR_DISK_USAGE_WARNING_MB $((OVE_LOG_DIR_DISK_USAGE_WARNING_MB * 10))"
			echo "- suppress this NOTE:"
			echo -e "\tove add-config ${OVE_GLOBAL_STATE_DIR}/.oveconfig OVE_LOG_DIR_DISK_USAGE_WARNING_MB 0"
		fi
	fi
}

function ove_aliases {
	local a
	local aliases

	if [[ $- != *i* ]]; then
		return
	elif [ "${OVE_ALIAS}" = "0" ]; then
		return
	elif [ "${OVE_ALIAS_LIST}" = "" ]; then
		return
	fi

	IFS=';' read -r -a aliases <<< "${OVE_ALIAS_LIST}"
	for a in "${!aliases[@]}"; do
		alias "${aliases[$a]}"
	done
}

# list-aliases: :list OVE aliases:CORE
function ove-list-aliases {
	ove_entry || return

	local a
	local aliases

	if [ "${OVE_ALIAS}" = "0" ]; then
		ove_echo_note_noprefix "OVE aliases are DISABLED, enable with 'ove add-config \$HOME/.oveconfig OVE_ALIAS 1'"
	fi

	IFS=';' read -r -a aliases <<< "${OVE_ALIAS_LIST}"
	for a in "${!aliases[@]}"; do
		echo "alias ${aliases[$a]}"
	done

	return 0
}

function ove_update_terminal_stats {
	if ! shopt -q checkwinsize; then
		shopt -s checkwinsize
		# force an update
		if [ -x /bin/true ]; then
			/bin/true
		fi

	fi

	if [ "${COLUMNS}" != "" ]; then
		OVE_COLUMNS=$COLUMNS
		OVE_LINES=$LINES
	else
		OVE_COLUMNS=
		OVE_LINES=
	fi
	export OVE_COLUMNS
	export OVE_LINES
}

function ove_setup_hub {
	local i
	local u
	local urls

	if [ "$OVE_HUB_URL_LIST" = "" ]; then
		return 1
	elif [ -d "${OVE_GLOBAL_STATE_DIR:?}"/hub ]; then
		return 0
	fi

	mapfile -t urls <<<"$(echo -e "${OVE_HUB_URL_LIST//;/\\n}")"
	i=0

	mkdir -p "${OVE_GLOBAL_STATE_DIR:?}"/hub
	while ((i < ${#urls[@]})); do
		u="${urls[$i]}"
		(( i+=1 ))
		if ! ${ove_cmd2pathname["git"]:?} clone -q "${u}" "${OVE_GLOBAL_STATE_DIR:?}"/hub/$i 2> /dev/null; then
			rm -rf "${OVE_GLOBAL_STATE_DIR:?}"/hub/$i
			ove_echo_error_noprefix "hub: 'git clone ${u}' failed"
		fi
	done
}

# refresh-hub: :refresh hub:CORE
function ove-refresh-hub {
	ove_entry || return

	local repo

	if ! ove_setup_hub; then
		return 0
	fi

	find "${OVE_GLOBAL_STATE_DIR:?}"/hub/ \
		-maxdepth 1 \
		-mindepth 1 \
		-type d |
		while read -r repo; do
			${ove_cmd2pathname["git"]:?} \
				-C "${repo:?}"/ \
				pull \
				--rebase \
				-q \
				|| true
		done
}

# purge-hub: :purge hub:CORE
function ove-purge-hub {
	ove_entry || return

	if [ ! -d "${OVE_GLOBAL_STATE_DIR:?}"/hub ]; then
		return 0
	fi

	${ove_cmd2pathname["rm"]:?} -rf "${OVE_GLOBAL_STATE_DIR:?}"/hub
}

# list-hub: :list hub:CORE
function ove-list-hub {
	ove_entry || return

	local repo

	if [ ! -d "${OVE_GLOBAL_STATE_DIR:?}"/hub ]; then
		return 0
	fi

	find "${OVE_GLOBAL_STATE_DIR:?}"/hub/ \
		-maxdepth 1 \
		-mindepth 1 \
		-type d |
		while read -r repo; do
			if [ ! -s "${repo}"/revtab ]; then
				continue
			fi

			# shellcheck disable=SC2016
			${ove_cmd2pathname["awk"]:?} '{print $2}' "${repo}"/revtab
		done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u
}

function ove_post_checks {
	local c
	local doublets

	# check for systest doublets
	if [ -e ${OVE_OWEL_DIR}/systests ]; then
		# yes, this is ugly
		# shellcheck disable=SC2016
		mapfile -t doublets < <(${ove_cmd2pathname["grep"]:?} -E -v '#|^$' ${OVE_OWEL_DIR}/systests | \
			${ove_cmd2pathname["awk"]:?} '{print $1}' | \
			${ove_cmd2pathname["cut"]:?} -d: -f1 | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
			${ove_cmd2pathname["uniq"]:?} -d)
		if [ "${doublets[*]}" != "" ]; then
			echo
			ove_echo_warning_noprefix "found ${#doublets[*]} systest duplicate(s):"
			for c in "${doublets[@]}"; do
				${ove_cmd2pathname["grep"]:?} -H -n -w ^${c} ${OVE_OWEL_DIR}/systests 1>&2
			done
		fi
	fi

	# keep ${HOME}/.ove.bash up-to-date
	if [ -e "${HOME}/.ove.bash" ] && ! ${ove_cmd2pathname["diff"]:?} -q "${OVE_DIR}/ove.bash" "${HOME}/.ove.bash" > /dev/null; then
		${ove_cmd2pathname["cp"]:?} "${OVE_DIR}/ove.bash" "${HOME}/.ove.bash"
	fi

	# inform user if logs etc. take too much space
	ove_disk_usage_check

	# validate revtab revision
	ove_revtab_check

	# patch repos
	ove_patch_repos || true

	# aliases
	ove_aliases

	ove_update_terminal_stats

	# incus
	if [ "${OVE_AUTO_INSTALL_INCUS}" = "1" ] && ! command -v incus > /dev/null; then
		${ove_cmd2pathname["bash"]:?} \
			"${OVE_DIR}"/hooks/incus/pre-distrocheck || true
	fi

	if [ "$OVE_HUB_URL_LIST" != "" ]; then
		ove_setup_hub
	fi

	return 0
}

function ove_buildable_projects {
	local deps
	local i
	local proj
	local proj_path
	local projs_and_deps_not_buildable
	local projs_not_buildable
	local repos_not_fetched
	local q
	local re
	declare -A projs_hash

	for q in ${OVE_REPO_LIST}; do
		if ove_dir_is_repo "${q}"; then
			continue
		fi
		repos_not_fetched+="${q} "
	done

	# remove projects with paths within git repos not yet fetched
	for q in ${repos_not_fetched}; do
		for proj in ${OVE_PROJECT_LIST}; do
			i=${ove_projects_name2index[${proj}]}
			proj_path="${ove_projects_path[${i}]}"
			if [ "${proj_path}" = "${q}" ] || [[ ${proj_path} == ${q}/* ]]; then
				if test "${projs_hash["${proj}"]+isset}"; then
					continue
				fi
				projs_hash["${proj}"]=1
				projs_not_buildable+="${proj} "
			fi
		done
	done

	if [ "${projs_not_buildable}" = "" ]; then
		unset OVE_PROJECT_LIST_BUILDABLE
		return
	fi

	# remove none buildable projects and its dependencies
	projs_and_deps_not_buildable="${projs_not_buildable}"
	for proj in ${OVE_PROJECT_LIST}; do
		deps=$(ove_get_deps_recursive ${proj})
		for q in ${projs_not_buildable}; do
			re=\\b${q}\\b
			if [[ "${deps}" =~ ${re} ]]; then
				re=\\b${proj}\\b
				# already marked as removed?
				if [[ "${projs_and_deps_not_buildable}" =~ ${re} ]]; then
					continue
				fi
				projs_and_deps_not_buildable+="${proj} "
			fi
		done
	done

	OVE_PROJECT_LIST_BUILDABLE=$(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -3 \
		<(printf "%s\n" ${OVE_PROJECT_LIST}) \
		<(printf "%s\n" ${projs_and_deps_not_buildable} | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}) |
		${ove_cmd2pathname["xargs"]:?})
	export OVE_PROJECT_LIST_BUILDABLE
}

# $1: dir
function ove_get_revision {
	local revision

	if [ ! -d "${1}" ]; then
		return 1
	fi

	# detached?
	if ! ${ove_cmd2pathname["git"]:?} -C "${1}" symbolic-ref -q HEAD > /dev/null; then
		revision=$(${ove_cmd2pathname["git"]:?} -C "${1}" rev-parse --short HEAD)
	else
		revision=$(${ove_cmd2pathname["git"]:?} -C "${1}" branch | \
			${ove_cmd2pathname["cut"]:?} -d' ' -f2 | \
			${ove_cmd2pathname["tr"]:?} -d '\n')
	fi

	echo "${revision}"
}

function ove_get_nbr_of_remotes {
	local array

	if [ ! -d "${1}" ]; then
		return 1
	elif ! mapfile -t array < <(${ove_cmd2pathname["git"]:?} -C "${1}" remote 2> /dev/null); then
		return 1
	fi

	echo "${#array[*]}"
}

# $1: dir
# $2: remote
function ove_get_fetch_url {
	local fetch_url

	if [ ! -d "${1}" ]; then
		return 1
	fi

	fetch_url=$(${ove_cmd2pathname["git"]:?} -C "${1}" remote get-url $2 2> /dev/null)
	if [ "${fetch_url}" = "" ]; then
		fetch_url="noremote"
	fi

	echo "${fetch_url}"
}

# $1: dir
# $2: remote
function ove_get_push_url {
	local push_url

	if [ ! -d "${1}" ]; then
		return 1
	fi

	push_url=$(${ove_cmd2pathname["git"]:?} -C "${1}" remote get-url --push $2 2> /dev/null)
	if [ "${push_url}" = "" ]; then
		push_url="noremote"
	fi

	echo "${push_url}"
}

# init:|[dir]|[dir name]:scan directories and look for git repositories, if found create/update a OVE workspace:CORE
function ove-init {
	ove_entry || return

	local d
	local dir
	local do_init_git
	local doublets
	local fetch_url
	local i
	local init_opt
	local name
	local ove_link
	local ove_default_branch
	local ove_url="https://github.com/Ericsson/ove.git"
	local owel_default
	local owel_name
	local push_url
	local repo
	local revision
	local revtabs
	local revtab_file
	local skeleton
	local str

	if [ $# -eq 0 ]; then
		while true; do
			read -r -p "directory to scan for git repositories? Leave blank to search in '$PWD': "
			if [ "${REPLY}" = "" ]; then
				if ove_is_base_dir "${PWD}"; then
					ove_echo_error_noprefix "'${PWD}' is already a OVE workspace. Remove the symblic link '${PWD}/.owel' to be able to re-init this directory."
					continue
				fi

				dir=${PWD}
				break
			fi

			if ! [ -d "${REPLY}" ]; then
				ove_echo_error_noprefix "'${REPLY}' is not a directory, try again"
				continue
			fi

			if ove_is_base_dir "${REPLY}"; then
				ove_echo_error_noprefix "'${REPLY}' is already a OVE workspace. Remove the symbolic link '${REPLY%/}/.owel' to be able to re-init this directory."
				continue
			fi
			dir=${REPLY}
			break
		done

	elif [ $# -lt 3 ]; then
		if ! [ -d ${1} ]; then
			ove_echo_error_noprefix "'${1}' is not a directory"
			return 1
		fi
		if ove_is_base_dir "${1}"; then
			ove_echo_error_noprefix "'${1}' is already a OVE workspace. Remove the symbolic link '${1%/}/.owel' to be able to re-init this directory."
			return 1
		fi
		dir=${1}
	fi

	if [ ${#dir} -ne 1 ]; then
		# remove trailing slash
		dir="${dir%/}"
	fi

	if ! [ -w "${dir}" ]; then
		ove_echo_error_noprefix "sorry you are not allowed to create files/directories here: '${dir}'"
		return 1
	fi

	if [ -e ${dir}/ove ] && ! [ -L ${dir}/ove ]; then
		ove_echo_error_noprefix "you already have a file/directory named '${dir}/ove', rename/remove to proceed"
		return 1
	fi

	mapfile -t revtabs < <(${ove_cmd2pathname["find"]:?} ${dir} -mindepth 2 -maxdepth 2 -name revtab 2> /dev/null)
	if [ $# -lt 2 ] && [ ${#revtabs[*]} -eq 1 ]; then
		owel_default="$(${ove_cmd2pathname["basename"]:?} $(${ove_cmd2pathname["dirname"]:?} ${revtabs[0]}))"
	else
		owel_default="top"
	fi

	if [ $# -eq 0 ] || [ $# -eq 1 ]; then
		while true; do
			read -r -p "OWEL name? Leave blank to name it '${owel_default}': "
			if [ "${REPLY}" = "" ]; then
				owel_name="${owel_default}"
			else
				owel_name="${REPLY}"
			fi
			break
		done
	elif [ $# -eq 2 ]; then
		owel_name=${2}
	fi

	dir=$(${ove_cmd2pathname["readlink"]:?} -f -- ${dir})
	i=0
	do_init_git=0

	# updating an existing git repo?
	# shellcheck disable=SC2016
	if [ -d ${dir}/${owel_name}/.git ]; then
		owel_remote=$(ove_get_fetch_url "${dir}/${owel_name}" origin)
	else
		do_init_git=1
	fi

	for repo in $(${ove_cmd2pathname["find"]:?} "${dir}" -type d -name .git 2>/dev/null); do
		if ! ${ove_cmd2pathname["git"]:?} -C ${repo} log -1 --oneline &> /dev/null; then
			continue
		fi

		name=$(${ove_cmd2pathname["dirname"]:?} "${repo}")
		name=${name/${dir}\//}

		if [ $(ove_get_nbr_of_remotes "${repo}") -gt 1 ]; then
			ove_echo_cyan_noprefix "select one remote for '${name}'"
			${ove_cmd2pathname["git"]:?} -C "${repo}" remote -v
			while true; do
				read -r -p "remote: "
				remote="${REPLY}"
				if ${ove_cmd2pathname["git"]:?} -C "${repo}" remote | ${ove_cmd2pathname["grep"]:?} -q ^${remote}$; then
					break;
				fi
			done
		else
			remote=$(${ove_cmd2pathname["git"]:?} -C "${repo}" remote)
		fi

		fetch_url=$(ove_get_fetch_url "${repo}" "${remote}")
		# ignore OWEL remote
		if [ "${fetch_url}" = "${owel_remote}" ]; then
			continue
		fi
		push_url=$(ove_get_push_url "${repo}" "${remote}")
		revision=$(ove_get_revision "${repo}")

		((i++))
		echo -en "Scanning '${dir}'. #repos: ${i}\r"
		str+="${name} ${fetch_url} ${push_url} ${revision}\n"
	done

	echo
	${ove_cmd2pathname["mkdir"]:?} -p ${dir}/${owel_name}

	if [ ${do_init_git} -eq 1 ]; then
		# Git v2.28
		if ${ove_cmd2pathname["git"]:?} init -h | ${ove_cmd2pathname["grep"]:?} -q '\-\-initial-branch'; then
			# $OVE_DEFAULT_BRANCH_NAME is not available at this moment
			init_opt="--initial-branch main"
		else
			init_opt=""
		fi

		if ! ${ove_cmd2pathname["git"]:?} -C ${dir}/${owel_name} init ${init_opt}; then
			ove_echo_error_noprefix "'git -C ${dir}/${owel_name} init ${init_opt}' failed"
			return 1
		fi
	fi

	# owel symlink
	(cd ${dir} && ${ove_cmd2pathname["ln"]:?} -s ${owel_name} .owel)

	if ! [ -L ${dir}/ove ]; then
		# clone myself
		if [ ! -d "$dir/.ove" ] && ! ${ove_cmd2pathname["git"]:?} -C "${dir}" clone -q "${ove_url}" .ove; then
			ove_echo_error_noprefix "'git -C ${dir} clone -q ${ove_url}' failed"
			return 1
		# get default branch name
		elif ! ove_default_branch=$(${ove_cmd2pathname["git"]:?} -C "${dir}/.ove" symbolic-ref refs/remotes/origin/HEAD); then
			ove_echo_error_noprefix "'git -C ${dir}/.ove symbolic-ref refs/remotes/origin/HEAD' failed"
			return 1
		fi
		ove_default_branch=${ove_default_branch##*/}
		str+=".ove ${ove_url} ${ove_url} ${ove_default_branch}\n"
		ove_link=".ove/ove"
		(cd ${dir} && ${ove_cmd2pathname["ln"]:?} -s ${ove_link} ove)
	fi

	if [ ${i} -ne 0 ]; then
		# create a revtab file
		revtab_file="${dir}/${owel_name}/revtab"
		printf "${str}" | \
			${ove_cmd2pathname["column"]:?} -t | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u > ${revtab_file}

		# inform user on repos with same fetch url
		# shellcheck disable=SC2016
		mapfile -t doublets < <(${ove_cmd2pathname["awk"]:?} '{print $2}' ${revtab_file} | ${ove_cmd2pathname["grep"]:?} -v noremote | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | ${ove_cmd2pathname["uniq"]:?} -d)
		if [ "${doublets[*]}" != "" ]; then
			ove_echo_note_noprefix "found a few repos with the same fetch url:"
			for d in "${doublets[@]}"; do
				${ove_cmd2pathname["grep"]:?} -H -n "${d}" ${revtab_file}
			done | ${ove_cmd2pathname["column"]:?} -t
		fi
	fi

	skeleton=0
	if [ -t 1 ]; then
		read -r -p "create example/skeleton files? (y/N) "
		if [[ ${REPLY} =~ ^[Yy]$ ]]; then
			skeleton=1
			# projs
			${ove_cmd2pathname["cat"]:?} > "${dir}/${owel_name}/projs" << EOF
---
base:
  needs:
    coreutils
  path:
    .

foobar:
  deps:
    base
  path:
    foobar
  version:
    0.1.0
EOF

			# projects
			${ove_cmd2pathname["mkdir"]:?} -p ${dir}/${owel_name}/projects/foobar

			for d in bootstrap configure build install test; do
				${ove_cmd2pathname["cat"]:?} > "${dir}/${owel_name}/projects/foobar/$d" << EOF
#!/usr/bin/env bash

echo "'$d' step for the OVE project named 'foobar'"
echo "OVE_ACTIVE_PROJECT_NAME=\$OVE_ACTIVE_PROJECT_NAME"
echo "OVE_ACTIVE_PROJECT_COMMAND=\$OVE_ACTIVE_PROJECT_COMMAND"
echo "OVE_ACTIVE_PROJECT_VERSION=\$OVE_ACTIVE_PROJECT_VERSION"
echo
echo "This script is located here: \$OVE_OWEL_DIR/projects/foobar/$d"
EOF
				${ove_cmd2pathname["chmod"]:?} +x ${dir}/${owel_name}/projects/foobar/$d
			done

			# scripts
			${ove_cmd2pathname["mkdir"]:?} -p ${dir}/${owel_name}/scripts
			${ove_cmd2pathname["cat"]:?} > "${dir}/${owel_name}/scripts/qwerty" << EOF
#!/usr/bin/env bash

echo "This is one OVE plugin named 'qwerty' and it is located here: \$OVE_OWEL_DIR/scripts/qwerty"
EOF
			${ove_cmd2pathname["chmod"]:?} +x ${dir}/${owel_name}/scripts/qwerty

			# SETUP
			echo "# add your oneliner in this file and the 'ove setup' will display it" > ${dir}/${owel_name}/SETUP

			# systests and systests-groups
			${ove_cmd2pathname["cat"]:?} > "${dir}/${owel_name}/systests" << EOF
# name       timeout (s)   type   path   command
t1           2             0      .      sleep 1
t2           1             0      .      sleep 2
EOF
			${ove_cmd2pathname["cat"]:?} > "${dir}/${owel_name}/systests-groups" << EOF
---
all:
  - t1
  - t2

sanity:
  - t1
EOF
		fi
	fi

	echo
	echo "Summary:"
	if [ ${i} -ne 0 ]; then
		echo "* created/updated '${revtab_file}' with ${i} repositories"
	fi
	if [ "${ove_link}" != "" ]; then
		echo "* created a symbolic link '${dir}/ove' -> '${ove_link}'"
	fi
	echo "* created a symbolic link '${dir}/.owel' -> '${dir}/${owel_name}'"

	if [ ${do_init_git} -eq 1 ]; then
		echo "* created an empty git repository here: '${dir}/${owel_name}'"
	fi
	if [ ${#doublets[*]} -ne 0 ]; then
		echo "* found that a few repos are mentioned more than one time in '${revtab_file}', details above"
	fi
	if [ ${dir} != "${PWD}" ]; then
		if ! cd ${dir}; then
			return 1
		fi
		echo "* changed current working directory to ${dir}"
	fi
	if [ ${skeleton} -eq 1 ]; then
		echo "* created these example/skeleton files:"
		${ove_cmd2pathname["find"]:?} ${dir}/${owel_name}/{projects,scripts,projs,SETUP} -type f
	fi
	echo
	echo "# now what?"
	echo
	echo "# check status"
	echo "$ ove status"
	echo
	if [ ${skeleton} -eq 1 ]; then
		echo "# try some OVE commands"
		echo "$ ove buildme foobar"
		echo "$ ove bootstrap foobar"
		echo "$ ove list-needs foobar"
		echo "$ ove qwerty"
		echo "$ ove systest t1"
		echo "$ ove systest all"
		echo
	fi
	echo "# add new repos/projects"
	echo "$ ove add-repo"
	echo "$ ove add-project"
	echo
	echo "# need help? ask OVE"
	echo "$ ove help"
}

function ove_debian_based {
	if [ "${OVE_OS_ID_LIKE,,}" = "debian" ]; then
		return 0
	elif [ "${OVE_OS_ID_LIKE,,}" = "ubuntu" ]; then
		return 0
	elif [[ ${OVE_OS,,} == *"debian"* ]]; then
		return 0
	elif [[ ${OVE_OS,,} == *"ubuntu"* ]]; then
		return 0
	else
		return 1
	fi
}

# $1: command
function ove_command_to_package {
	local package

	# column
	if [ "$1" = "column" ]; then
		if ove_debian_based; then
			package="bsdmainutils"
		elif [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="sys-apps/util-linux"
		else
			package="util-linux"
		fi
	# flock
	elif [ "$1" = "flock" ]; then
		if [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="sys-apps/util-linux"
		else
			package="util-linux"
		fi
	# git
	elif [ "$1" = "git" ]; then
		if [[ ${OVE_OS,,} == *"alpine"* ]]; then
			package="git git-perl"
		elif [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="dev-vcs/git"
		fi
	# ld
	elif [ "$1" = "ld" ]; then
		package="binutils"
	# less
	elif [ "$1" = "less" ]; then
		if [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="sys-apps/less"
		fi
	# locate
	elif [ "$1" = "locate" ]; then
		package="mlocate"
	# pgrep
	elif [ "$1" = "pgrep" ]; then
		if ove_debian_based; then
			package="procps"
		fi
	# script
	elif [ "$1" = "script" ]; then
		if ove_debian_based; then
			package="bsdutils"
		elif [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="sys-apps/util-linux"
		else
			package="util-linux"
		fi
	# gtac
	elif [ "$1" = "gtac" ]; then
		package="coreutils"
	# tsort
	elif [ "$1" = "tsort" ]; then
		package="coreutils"
	# xz
	elif [ "$1" = "xz" ]; then
		if ove_debian_based; then
			package="xz-utils"
		elif [[ ${OVE_OS,,} == *"gentoo"* ]]; then
			package="app-arch/xz"
		fi
	fi

	if [ "${package}" != "" ]; then
		echo ${package}
	else
		echo $1
	fi
}

function ove_deps {
	local dep
	local deps
	local pack
	local optional
	local str_cmds
	local str_packs

	str_packs=""
	str_cmds=""

	deps=()
	deps+=('bzip2')
	deps+=('column')
	deps+=('file')
	deps+=('flock')
	deps+=('git')
	deps+=('gzip')
	deps+=('less')
	deps+=('pgrep')
	deps+=('script')
	deps+=('tar')
	deps+=('tsort')
	if [[ "${OVE_OS_KERNEL,,}" == *bsd* ]]; then
		deps+=('gcc')
		deps+=('gtac')
	else
		deps+=('ld')
	fi

	optional=()
	optional+=('ag')
	optional+=('convert')
	optional+=('dig')
	optional+=('dot')
	optional+=('ffmpeg')
	optional+=('fzf')
	optional+=('graph-easy')
	optional+=('inotifywait')
	optional+=('jp2a')
	optional+=('incus')
	optional+=('locate')
	optional+=('lxc')
	optional+=('make')
	optional+=('md5deep')
	optional+=('recordmydesktop')
	optional+=('rg')
	optional+=('shellcheck')
	optional+=('sshpass')
	optional+=('strace')
	optional+=('task')
	optional+=('tmux')
	optional+=('tsp')
	optional+=('whois')
	optional+=('yamllint')
	optional+=('xdotool')
	optional+=('xpra')

	for dep in "${deps[@]}"; do
		if ! command -v ${dep} > /dev/null; then
			str_cmds+="${dep} "
			pack=$(ove_command_to_package ${dep})
			if [ "${pack}" != "" ]; then
				str_packs+="${pack} "
			fi
		fi
	done

	if [ "${str_cmds}" != "" ]; then
		ove_echo_error_noprefix "missing command(s):"
		echo
		for dep in ${str_cmds}; do
			echo -e "\t${dep}"
		done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
		echo
		echo "To fix this, run the following command:"
		echo
		echo -e "\t${OVE_OS_PACKAGE_MANAGER} ${OVE_OS_PACKAGE_MANAGER_ARGS} $(printf "%s " $(ove_uniq ${str_packs}))"
		echo

		str_cmds=""
		for dep in "${optional[@]}"; do
			if ! command -v ${dep} > /dev/null; then
				str_cmds+="${dep} "
			fi
		done

		if [ "${str_cmds}" != "" ]; then
			echo "[optional]: command(s) needed to unlock all OVE features:"
			echo
			for dep in ${str_cmds}; do
				echo -e "\t${dep}"
			done | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
		fi
		return 1
	fi

	if ! ove_version_check; then
		return 1
	fi

	return 0
}

# $*: list of packages
# returns a list of packages NOT installed
function ove_packages_not_installed {
	local p_sort

	if [ $# -eq 0 ]; then
		return
	fi

	p_sort=$(printf "%s\n" "$@" | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u)

	if [[ ${OVE_OS,,} == *"arch linux"* ]]; then
		# shellcheck disable=SC2016
		LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 <(printf "%s\n" ${p_sort}) <(\pacman -Q | ${ove_cmd2pathname["awk"]:?} '{print $1}')
	elif [[ ${OVE_OS,,} == *"alpine"* ]]; then
		LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 <(printf "%s\n" ${p_sort}) <(\apk info | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	elif [[ ${OVE_OS,,} == *"centos"* ]] || \
		[[ ${OVE_OS,,} == *"fedora"* ]] || \
		[[ ${OVE_OS,,} == *"sles"* ]] || \
		[[ ${OVE_OS,,} == *"opensuse"* ]] || \
		[[ ${OVE_OS,,} == *"redhatenterpriseserver"* ]] ||
		[[ ${OVE_OS_ID_LIKE,,} == *rhel* ]] ||
		[[ ${OVE_OS_ID_LIKE,,} == *centos* ]] ||
		[[ ${OVE_OS_ID_LIKE,,} == *fedora* ]]; then
		LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 <(printf "%s\n" ${p_sort}) <(\rpm -qa --qf "%{NAME}\n"| LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	elif ove_debian_based; then
		LANG=C.UTF-8 \dpkg-query -W -f='${Package}:${Status}\n' ${p_sort} 2>&1 | \
			${ove_cmd2pathname["grep"]:?} -v ":install ok installed" | \
			${ove_cmd2pathname["sed"]:?} -e 's/dpkg-query: no packages found matching //g' -e 's/:.*//g' | \
			${ove_cmd2pathname["xargs"]:?}
	elif [[ ${OVE_OS,,} == *"void"* ]]; then
		# shellcheck disable=SC2016
		LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 \
			<(printf "%s\n" ${p_sort}) \
			<(\xbps-query --list-pkgs | \
			${ove_cmd2pathname["awk"]:?} '{print $2}' | \
			${ove_cmd2pathname["rev"]:?} | \
			${ove_cmd2pathname["cut"]:?} -d- -f2- | \
			${ove_cmd2pathname["rev"]:?} | \
			LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
			${ove_cmd2pathname["xargs"]:?} -n1)
	elif [[ ${OVE_OS,,} == *"bsd"* ]]; then
		LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -2 -3 <(printf "%s\n" ${p_sort}) <(\pkg query -e '%a = 0' '%n' | LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	else
		ove_echo_error_noprefix "function '${FUNCNAME[0]}' is not implemented for ${OVE_OS}"
	fi
}

function ove_determine_dist_version_and_pack_manager {
	# OVE_OS:Distribution NAME
	OVE_OS=
	# OVE_OS_ID:Distribution ID
	OVE_OS_ID=
	# OVE_OS_VER:Distribution version
	OVE_OS_VER=
	# OVE_OS_ID_LIKE:Distribution ID_LIKE
	OVE_OS_ID_LIKE=
	# OVE_OS_CODENAME:Distribution code name
	OVE_OS_CODENAME=
	# OVE_OS_KERNEL:Operating system implementation
	OVE_OS_KERNEL=
	if [ -e /etc/os-release ]; then
		OVE_OS=$(source /etc/os-release; echo ${NAME})
		OVE_OS_ID=$(source /etc/os-release; echo ${ID})
		OVE_OS_VER=$(source /etc/os-release; echo ${VERSION_ID})
		OVE_OS_ID_LIKE=$(source /etc/os-release; echo ${ID_LIKE:-$ID})
		OVE_OS_CODENAME=$(source /etc/os-release; echo ${VERSION_CODENAME:-$ID})
	elif command -v lsb_release > /dev/null; then
		OVE_OS=$(${ove_cmd2pathname["lsb_release"]:?} --id --short)
		OVE_OS_ID=${OVE_OS}
		OVE_OS_VER=$(${ove_cmd2pathname["lsb_release"]:?} --release --short)
		OVE_OS_CODENAME=$(${ove_cmd2pathname["lsb_release"]:?} --codename --short)
	else
		OVE_OS=$(${ove_cmd2pathname["uname"]:?} -s)
		OVE_OS_ID=${OVE_OS}
		OVE_OS_VER=$(${ove_cmd2pathname["uname"]:?} -r)
	fi

	OVE_OS_KERNEL=$(${ove_cmd2pathname["uname"]:?} -o 2> /dev/null)

	# OVE_OS_PACKAGE_MANAGER:package manager
	OVE_OS_PACKAGE_MANAGER=
	# OVE_OS_PACKAGE_MANAGER_ARGS:package manager arguments
	OVE_OS_PACKAGE_MANAGER_ARGS=
	if [[ ${OVE_OS,,} == *"alpine"* ]]; then
		OVE_OS_PACKAGE_MANAGER="apk"
		OVE_OS_PACKAGE_MANAGER_ARGS="add"
	elif [[ ${OVE_OS,,} == *"arch linux"* ]]; then
		OVE_OS_PACKAGE_MANAGER="pacman"
		OVE_OS_PACKAGE_MANAGER_ARGS="-S"
	elif [[ ${OVE_OS,,} == *"centos"* ]]; then
		OVE_OS_PACKAGE_MANAGER="yum"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	elif ove_debian_based; then
		OVE_OS_PACKAGE_MANAGER="apt"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	elif [[ ${OVE_OS,,} == *"fedora"* ]] || \
		[[ ${OVE_OS,,} == *"redhatenterpriseserver"* ]] || \
		command -v dnf > /dev/null; then
		OVE_OS_PACKAGE_MANAGER="dnf"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	elif [[ ${OVE_OS,,} == *"gentoo"* ]]; then
		OVE_OS_PACKAGE_MANAGER="emerge"
		OVE_OS_PACKAGE_MANAGER_ARGS=""
	elif [[ ${OVE_OS,,} == *"opensuse"* ]] || \
		[[ ${OVE_OS,,} == *"sles"* ]]; then
		OVE_OS_PACKAGE_MANAGER="zypper"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	elif [[ ${OVE_OS,,} == *"void"* ]]; then
		OVE_OS_PACKAGE_MANAGER="xbps-install"
		OVE_OS_PACKAGE_MANAGER_ARGS=""
	elif [[ ${OVE_OS,,} == *"openwrt"* ]]; then
		OVE_OS_PACKAGE_MANAGER="opkg"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	elif [[ ${OVE_OS,,} == *"bsd"* ]]; then
		OVE_OS_PACKAGE_MANAGER="pkg"
		OVE_OS_PACKAGE_MANAGER_ARGS="install"
	else
		OVE_OS_PACKAGE_MANAGER="unknown"
		OVE_OS_PACKAGE_MANAGER_ARGS=""
	fi

	export OVE_OS
	export OVE_OS_ID
	export OVE_OS_VER
	export OVE_OS_ID_LIKE
	export OVE_OS_CODENAME
	export OVE_OS_KERNEL
	export OVE_OS_PACKAGE_MANAGER
	export OVE_OS_PACKAGE_MANAGER_ARGS
}

# fsck:[git...]:git fsck --full for all/specified git repositories:DEBUG
function ove-fsck {
	ove_entry || return

	declare -a repos
	local cmd

	cmd="ove_echo_yellow_noprefix \$(pwd -P) && \
		ALLOW_OVERRIDE=1 ove_repo_cmd \${repo} fsck || \
		ove_echo_error_noprefix \'${ove_cmd2pathname["git"]:?} -C \$(pwd -P) fsck\' returned != 0, corrupt repo?; echo"

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
		if [ "${#repos[@]}" -eq 0 ]; then
			return
		fi
		ove_revtab_forsome "${cmd}" "${repos[@]}"
	fi
}

# show-dangling:[git...]:show dangling git objects (=blob|commit|tag|tree) for all/specified git repositories:DEBUG
function ove-show-dangling {
	ove_entry || return

	local sha_list

	# shellcheck disable=SC2016
	sha_list=$(ove-fsck "$@" | ${ove_cmd2pathname["grep"]:?} '^dangling' | ${ove_cmd2pathname["awk"]:?} '{print $3}')
	if [ "${sha_list}" != "" ]; then
		ove-show ${sha_list}
	fi
}

# readme:[git...]:display README files for all/specified git repositories:UTIL
function ove-readme {
	ove_entry || return

	declare -a repos
	local cmd

	# shellcheck disable=SC2016
	cmd='${ove_cmd2pathname["find"]:?} ${PWD} -maxdepth 1 -name "README*" -print0 | '
	# shellcheck disable=SC2016
	cmd+='${ove_cmd2pathname["xargs"]:?} -r -0 ${ove_cmd2pathname["head"]:?} -v |'
	# shellcheck disable=SC2016
	cmd+='${ove_cmd2pathname["sed"]:?} -e "1 i$(ove_echo_yellow_noprefix $(pwd -P))" -e "s/^/\t/g"'

	if [ $# -eq 0 ]; then
		ove_revtab_forall "${cmd}"
	else
		mapfile -t repos < <(ove_validate_repo_list "$@")
		if [ "${#repos[@]}" -eq 0 ]; then
			return
		fi
		ove_revtab_forsome "${cmd}" "${repos[@]}"
	fi
}

# $1: worktree name
# $2: rev to checkout [optional]
function ove_worktree_add {
	local i
	local name
	local revision
	local worktree
	local worktree_base
	local worktree_dir

	if [ $# -eq 0 ] || [ $# -ge 3 ]; then
		return 1
	fi

	if ! worktree="$(${ove_cmd2pathname["readlink"]:?} -f -- $1)"; then
		ove_echo_error_noprefix "$1 is not a valid path"
		return 1
	fi
	worktree_base="${worktree##*/}"
	worktree_dir="${worktree%/*}"

	if [[ ${worktree} == ${OVE_BASE_DIR}/* ]]; then
		ove_echo_error_noprefix "use a path that is outside of the OVE workspace"
		return 1
	elif [ -d "${worktree}" ]; then
		ove_echo_error_noprefix "'${worktree}' already exist"
		return 1
	elif [ -h "${OVE_OWEL_STATE_DIR}/worktree/${worktree_base}" ]; then
		ove_echo_error_noprefix "'${worktree_base}' name is already taken"
		return 1
	elif [ ! -w "${worktree_dir}" ]; then
		ove_echo_error_noprefix "'${worktree_dir}' is not writable"
		return 1
	elif [ -f "${worktree}" ]; then
		ove_echo_error_noprefix "'${worktree}' is a regular file"
		return 1
	fi

	if [ $# -eq 2 ]; then
		if ! ove_repo_cmd "${OVE_OWEL_DIR}" cat-file -e "$2" &> /dev/null; then
			ove_echo_error_noprefix "'$2' is not a valid revision"
			return 1
		fi

		# get revtab for revision '$2'
		${ove_cmd2pathname["mkdir"]:?} -p ${OVE_OWEL_TMP_DIR}/worktree
		ove_repo_cmd "${OVE_OWEL_DIR}" show $2:revtab > ${OVE_OWEL_TMP_DIR}/worktree/revtab
		if [ ! -s ${OVE_OWEL_TMP_DIR}/worktree/revtab ]; then
			ove_echo_error_noprefix "revtab was empty/non-existing in '$2'"
			return 1
		fi

		(
			# run this in a subshell
			OVE_OWEL_DIR=${OVE_OWEL_TMP_DIR}/worktree ove_revtab_init
			i=0
			while ((i < ove_revtab_num_repositories)); do
				name=${ove_revtab_git_name[${i}]}
				revision=${ove_revtab_rev[${i}]}
				if [ ! -d $OVE_BASE_DIR/${name} ]; then
					ove_echo_warning_noprefix "$OVE_BASE_DIR/${name} is missing"
					continue
				fi
				ove_repo_cmd "$OVE_BASE_DIR/${name}" worktree add -B ove-worktree-${worktree_base} -f ${worktree}/${name} ${revision}
				(( i+=1 ))
			done
			ove_repo_cmd "$OVE_OWEL_DIR" worktree add -B ove-worktree-${worktree_base} -f ${worktree}/$OVE_OWEL_NAME $2
		)
	else
		ove_revtab_forall "ove_repo_cmd \$repo worktree add -B ove-worktree-${worktree_base} -f ${worktree}/\$repo_basename &> /dev/null"
	fi

	(cd ${worktree} || return 1; [ -h ove ]   || ${ove_cmd2pathname["ln"]:?} -s ${OVE_SELF/$OVE_BASE_DIR\/} ove)
	(cd ${worktree} || return 1; [ -h .owel ] || ${ove_cmd2pathname["ln"]:?} -s $OVE_OWEL_NAME .owel)

	${ove_cmd2pathname["mkdir"]:?} -p $OVE_OWEL_STATE_DIR/worktree
	(cd $OVE_OWEL_STATE_DIR/worktree || return 1; ${ove_cmd2pathname["ln"]:?} -s ${worktree} ${worktree_base})

	ove_worktree_list ${worktree_base}

	return 0
}

function ove_worktree_gc {
	local broken_links

	if [ ! -d $OVE_OWEL_STATE_DIR/worktree ]; then
		return
	fi

	broken_links=$(${ove_cmd2pathname["find"]:?} $OVE_OWEL_STATE_DIR/worktree/ -maxdepth 1 -type l ! -exec test -e {} \; -print)
	if [ "${broken_links}" != "" ]; then
		${ove_cmd2pathname["rm"]:?} ${broken_links}
	fi
}

function ove_worktree_remove {
	local ret
	local w
	local worktree
	local worktree_base

	if [ $# -eq 0 ]; then
		return 1
	fi

	ret=0
	for w in $(ove_uniq "$@"); do
		worktree="$OVE_OWEL_STATE_DIR/worktree/${w##*/}"
		if [ ! -e "${worktree}" ]; then
			((ret++))
			continue
		fi

		ove_revtab_forall "git worktree remove ${worktree}/\$repo_basename 2> /dev/null"
		${ove_cmd2pathname["rm"]:?} -rf ${worktree:?}/
		${ove_cmd2pathname["rmdir"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${worktree})
		worktree_base="${worktree##*/}"
		if [ -h "$OVE_OWEL_STATE_DIR/worktree/${worktree_base}" ]; then
			rm "$OVE_OWEL_STATE_DIR/worktree/${worktree_base}"
		fi
	done

	return ${ret}
}

# $1: worktree path
function ove_worktree_status_one {
	if ! ove_is_base_dir "$1"; then
		ove_echo_yellow_noprefix "worktree '$(${ove_cmd2pathname["readlink"]:?} -f -- $1)' is corrupt, fixme!"
		return 1
	fi

	ove_echo_green_noprefix "$(${ove_cmd2pathname["readlink"]:?} -f -- $1)"
	${ove_cmd2pathname["bash"]:?} -i -c "cd $1; . ove hush; ove status"
}

# $1: worktree basename
function ove_worktree_status {
	local d
	local d_base

	if [ ! -d $OVE_OWEL_STATE_DIR/worktree ]; then
		return 1
	fi

	if [ $# -eq 0 ]; then
		for d in $(${ove_cmd2pathname["find"]:?} $OVE_OWEL_STATE_DIR/worktree/ -mindepth 1 -maxdepth 1 -type l 2> /dev/null | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -V); do
			if [ ! -d "${d}" ]; then
				ove_echo_yellow_noprefix "worktree '$(${ove_cmd2pathname["readlink"]:?} -f -- $d)' is not a directory as expected, fixme!"
				continue
			fi

			ove_worktree_status_one "${d}"
		done

	else
		for d in $(ove_uniq "$@"); do
			d_base=${d##*/}
			if [ -d $OVE_OWEL_STATE_DIR/worktree/${d_base} ]; then
				ove_worktree_status_one "$OVE_OWEL_STATE_DIR/worktree/${d_base}"
			fi
		done
	fi

	return 0
}

# $1: worktree basename
function ove_worktree_list {
	local d
	local d_base

	if [ ! -d $OVE_OWEL_STATE_DIR/worktree ]; then
		return 1
	fi

	if [ $# -eq 0 ]; then
		for d in $(${ove_cmd2pathname["find"]:?} $OVE_OWEL_STATE_DIR/worktree/ -mindepth 1 -maxdepth 1 -type l 2> /dev/null | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -V); do
			if [ ! -d "${d}" ]; then
				ove_echo_yellow_noprefix "worktree '$(${ove_cmd2pathname["readlink"]:?} -f $d)' is not a directory as expected, fixme!"
				continue
			fi

			ove_echo_green_noprefix "$(${ove_cmd2pathname["readlink"]:?} -f -- ${d})"
		done

	else
		for d in $(ove_uniq "$@"); do
			d_base=${d##*/}
			if [ -d $OVE_OWEL_STATE_DIR/worktree/${d_base} ]; then
				ove_echo_green_noprefix "$(${ove_cmd2pathname["readlink"]:?} -f -- $OVE_OWEL_STATE_DIR/worktree/${d_base})"
			fi
		done
	fi

	return 0
}

# worktree:[add <path> [rev]]|list [worktree...]|prune|remove worktree...|status [worktree...]]:replicate OVE workspace on this host using 'git worktree':CORE
function ove-worktree {
	ove_entry || return
	local name

	ove_worktree_gc

	if [ $# -eq 0 ]; then
		ove_worktree_list
	elif [ $# -ge 1 ] && [ "$1" = "list" ]; then
		shift
		ove_worktree_list "$@"
	elif [ $# -ge 1 ] && [ "$1" = "status" ]; then
		shift
		ove_worktree_status "$@"
	elif [ $# -eq 1 ] && [ "$1" = "prune" ]; then
		ove_revtab_forall 'git worktree prune -v'
	elif [ $# -ge 2 ] && [ "$1" = "remove" ]; then
		shift
		if ! ove_worktree_remove "$@"; then
			return 1
		fi
	elif [ $# -ge 2 ] && [ "$1" = "add" ]; then
		shift
		if ! ove_worktree_add "$@"; then
			return 1
		fi
	else
		ove_command_usage
		return 1
	fi

	return 0
}

# replicate-cluster-parallel:[force [pull]|save [msg]|nofetch]:replicate-cluster in parallel (incus|LXD only):UTIL
function ove-replicate-cluster-parallel {
	ove-replicate-cluster "$@"
}

function ove_container_command {
	if command -v "incus" > /dev/null; then
		echo "incus"
	elif command -v "lxc" > /dev/null; then
		echo "lxc"
	else
		ove_echo_fatal_noprefix "no container runtime found"
		return 1
	fi

	return 0
}

# replicate-cluster:[force [pull]|save [msg]|nofetch]:replicate OVE workspace on all cluster members (incus|LXD only):UTIL
function ove-replicate-cluster {
	local c
	local h
	local p
	local s

	if ! c=$(ove_container_command); then
		return 1
	elif ! ${ove_cmd2pathname[$c]:?} cluster list &> /dev/null; then
		ove_echo_error_noprefix "this host is not part of a $c cluster"
		return 1
	fi

	p=0
	if [ ${#FUNCNAME[*]} -eq 2 ] && \
		[[ ${FUNCNAME[1]} == ${FUNCNAME[0]}-parallel ]]; then
		p=1
	fi

	# shellcheck disable=SC2016
	s=$(${ove_cmd2pathname["$c"]:?} info | \
		${ove_cmd2pathname["grep"]:?} server_name | \
		${ove_cmd2pathname["awk"]:?} '{print $2}')
	if [ "${s}" = "" ]; then
		ove_echo_fatal_noprefix "could not get 'server_name'"
		return 0
	fi

	for h in $(${ove_cmd2pathname["$c"]:?} cluster list --format csv | \
		${ove_cmd2pathname["grep"]:?} ONLINE | \
		${ove_cmd2pathname["cut"]:?} -d, -f1); do
		if [ "${s}" != "${h}" ]; then
			if [ $p -eq 1 ]; then
				ove-replicate "${h}" "${OVE_BASE_DIR}" "$@" &
			elif ! ove-replicate "${h}" "${OVE_BASE_DIR}" "$@"; then
				return 1
			fi
		fi
	done

	if [ $p -eq 1 ]; then
		wait
	fi

	return 0
}

# replicate:host [path [force [pull|nofetch]|save [msg]|nofetch]]:replicate OVE workspace on 'host':UTIL
function ove-replicate {
	ove_entry || return

	local d
	local host
	local fetch=1
	local md5
	local n
	local n_base
	local now
	local o
	local p
	local q
	local repos
	local ret=0
	local run_setup
	local s

	if [ $# -eq 0 ] || [ $# -gt 4 ]; then
		ove_command_usage
		return 1
	fi

	host="$1"
	if [ "${host}" = "localhost" ]; then
		run_setup=0
		if [ $# -eq 1 ]; then
			d=$(${ove_cmd2pathname["mktemp"]:?} -d)
			run_setup=1
		elif ! d=$(${ove_cmd2pathname["readlink"]:?} -f $2); then
			d="$2"
			run_setup=1
		elif ! [ -L ${d}/ove ] && ! [ -L ${d}/.owel ]; then
			if ! ${ove_cmd2pathname["mkdir"]:?} -p $2; then
				return 1
			fi
			d="$2"
			run_setup=1
		fi
	else
		if ! ${ove_cmd2pathname["ssh"]:?} -q ${host} exit 0; then
			ove_echo_error_noprefix "'${host}' is not reachable via ssh"
			return 1
		fi

		run_setup=0
		if [ $# -eq 1 ]; then
			d=$(${ove_cmd2pathname["ssh"]:?} ${host} mktemp -d)
			run_setup=1
		elif ! d=$(${ove_cmd2pathname["ssh"]:?} ${host} readlink -f $2); then
			d="$2"
			run_setup=1
		elif ! ${ove_cmd2pathname["ssh"]:?} -q ${host} "[ -L ${d}/ove ] && [ -L ${d}/.owel ]"; then
			if ! ${ove_cmd2pathname["ssh"]:?} ${host} mkdir -p $2; then
				return 1
			fi
			d="$2"
			run_setup=1
		fi
	fi

	if [ ${run_setup} -eq 1 ]; then
		if [ ! -e "${OVE_OWEL_DIR}/SETUP" ]; then
			ove_echo_error_noprefix "'${OVE_OWEL_DIR}/SETUP' not found"
			return 1
		elif [ ! -s "${OVE_OWEL_DIR}/SETUP" ]; then
			ove_echo_error_noprefix "'${OVE_OWEL_DIR}/SETUP' is empty"
			return 1
		elif ! s="$(${ove_cmd2pathname["cat"]:?} ${OVE_OWEL_DIR}/SETUP)"; then
			return 1
		fi
	fi

	now=$(${ove_cmd2pathname["date"]:?} '+%Y%m%d-%H%M%S%N')
	q="$(${ove_cmd2pathname["mktemp"]:?} -u -p ${OVE_OWEL_TMP_DIR}).tar.bz2"
	ove-format-patch "${q}" &> /dev/null
	if [ -s "${q}" ]; then
		q_remote="${d}/${now}.tar.bz2"
		if [ "${host}" != "localhost" ] && ! ${ove_cmd2pathname["scp"]:?} -q ${q} ${host}:${q_remote}; then
			ove_echo_error_noprefix "scp ${q} ${host}:${q_remote} failed"
			${ove_cmd2pathname["rm"]:?} ${q}
			return 1
		fi
	elif [ -e "${q}" ]; then
		${ove_cmd2pathname["rm"]:?} "${q}"
	fi

	p=$(${ove_cmd2pathname["mktemp"]:?} -p ${OVE_OWEL_TMP_DIR})
	ove-diff > "${p}"
	if [ -s "${p}" ]; then
		p_remote="${d}/${now}.diff"
		if [ "${host}" != "localhost" ] && ! ${ove_cmd2pathname["scp"]:?} -q ${p} ${host}:${p_remote}; then
			ove_echo_error_noprefix "scp ${p} ${host}:${p_remote} failed"
			${ove_cmd2pathname["rm"]:?} ${p} ${q} 2> /dev/null
			return 1
		fi
	elif [ -e "${p}" ]; then
		${ove_cmd2pathname["rm"]:?} "${p}"
	fi

	o=$(${ove_cmd2pathname["mktemp"]:?} -p ${OVE_OWEL_TMP_DIR})
	ove-diff-cached > "${o}"
	if [ -s "${o}" ]; then
		o_remote="${d}/${now}.cached"
		if [ "${host}" != "localhost" ] && ! ${ove_cmd2pathname["scp"]:?} -q ${o} ${host}:${o_remote}; then
			ove_echo_error_noprefix "scp ${o} ${host}:${o_remote} failed"
			${ove_cmd2pathname["rm"]:?} ${p} ${q} ${o} 2> /dev/null
			return 1
		fi
	elif [ -e "${o}" ]; then
		${ove_cmd2pathname["rm"]:?} "${o}"
	fi

	if [ $# -ge 3 ] && [ "$3" = "nofetch" ]; then
		fetch=0
	elif [ $# -eq 4 ] && [ "$3" = "force" ] && [ "$4" = "nofetch" ]; then
		fetch=0
	elif [ ${OVE_REPOS_FETCHED} -lt $(${ove_cmd2pathname["wc"]:?} -w <<<"${OVE_REPO_LIST}") ]; then
		# shellcheck disable=SC2016
		repos="$(ove-status | ${ove_cmd2pathname["awk"]:?} '{print $1}')"
		repos=${repos//$'\n'/ }
	fi

	if [ "${host}" = "localhost" ]; then
		if ! cd ${d}; then
			return
		fi
		if [ ${run_setup} -eq 1 ]; then
			if ! ${ove_cmd2pathname["touch"]:?} .ref; then
				return
			fi
			set -o pipefail
			if ! eval ${s} > /dev/null; then
				return 1
			fi
			n=$(${ove_cmd2pathname["find"]:?} ${PWD} -maxdepth 1 -mindepth 1 -type d -newer .ref)
			n_base=${n##*/}
			if ! cd $n; then
				return
			elif [ -e ../.ref ]; then
				${ove_cmd2pathname["rm"]:?} ../.ref
			fi
		fi
		if ! source ove hush; then
			return
		fi
		if [ ${run_setup} -eq 1 ] && [ ${fetch} -eq 1 ]; then
			ove-fetch ${repos} &> /dev/null
		fi

		if [ $# -ge 3 ] && [ "$3" = "force" ]; then
			ove-stash &> /dev/null
			ove-stash drop &> /dev/null
			ove-reset-ahead &> /dev/null
			if [ $# -eq 4 ] && [ "$4" = "pull" ]; then
				ove-fetch &> /dev/null
				ove-pull &> /dev/null
				ove-stash &> /dev/null
				ove-revtab-sync &> /dev/null
				ove-stash pop &> /dev/null
			fi
		elif [ $# -ge 3 ] && [ "$3" = "save" ]; then
			if [ $# -eq 4 ]; then
				ove-stash push "$4" &> /dev/null
				ove-format-patch "$4" &> /dev/null
			else
				ove-stash &> /dev/null
				ove-format-patch &> /dev/null
			fi
			ove-reset-ahead &> /dev/null
		fi

		md5=$(${ove_cmd2pathname["md5sum"]:?} $OVE_OWEL_DIR/revtab)
		if [ -s "${q}" ]; then
			ove-am "${q}" &> /dev/null
			${ove_cmd2pathname["rm"]:?} "${q}"
		fi

		if [ -s "${o}" ]; then
			ove-apply-cached "${o}" &> /dev/null
			${ove_cmd2pathname["rm"]:?} "${o}"
		fi

		if [ -s "${p}" ]; then
			ove-apply "${p}" &> /dev/null
			${ove_cmd2pathname["rm"]:?} "${p}"
		fi

		# one extra fetch if revtab was changed
		if [ "$md5" != "$(${ove_cmd2pathname["md5sum"]:?} $OVE_OWEL_DIR/revtab)" ] && \
			[ ${fetch} -eq 1 ]; then
			if ove_init; then
				ove-fetch &> /dev/null
			fi
		fi

		if [ ${run_setup} -eq 1 ]; then
			if ! cd ..; then
				return
			elif [ ${OVE_BASE_DIR##*/} = ${OVE_OWEL_NAME} ]; then
				mv ${OVE_OWEL_NAME} ${OVE_OWEL_NAME}a
				n_base=${OVE_OWEL_NAME}a
			fi
			if ! ${ove_cmd2pathname["mv"]:?} ${n_base}/{.[!.],}* .; then
				return
			elif ! ${ove_cmd2pathname["rmdir"]:?} ${n_base}; then
				return
			fi
		fi
	elif ! ${ove_cmd2pathname["ssh"]:?} ${host} "
		if ! cd ${d}; then
			exit
		fi
		if [ ${run_setup} -eq 1 ]; then
			if ! touch .ref; then
				exit
			fi
			set -o pipefail
			if ! eval ${s} > /dev/null; then
				exit 1
			fi
			n=\$(\find \${PWD} -maxdepth 1 -mindepth 1 -type d -newer .ref)
			n_base=\${n##*/}
			if ! cd \${n}; then
				exit
			elif [ -e ../.ref ]; then
				rm ../.ref
			fi
		fi
		if ! source ove hush; then
			exit
		elif [ ${run_setup} -eq 1 ] && [ ${fetch} -eq 1 ]; then
			ove-fetch ${repos} &> /dev/null
		fi
		if [ $# -ge 3 ] && [ $3 = force ]; then
			ove-stash
			ove-stash drop &> /dev/null
			ove-reset-ahead &> /dev/null
			if [ $# -eq 4 ] && [ $4 = pull ]; then
				ove-fetch &> /dev/null
				ove-pull &> /dev/null
				ove-stash &> /dev/null
				ove-revtab-sync &> /dev/null
				ove-stash pop &> /dev/null
			fi
		elif [ $# -ge 3 ] && [ $3 = save ]; then
			if [ $# -eq 4 ]; then
				ove-stash push $4 &> /dev/null
				ove-format-patch $4 &> /dev/null
			else
				ove-stash &> /dev/null
				ove-format-patch &> /dev/null
			fi
			ove-reset-ahead &> /dev/null
		fi
		md5=\$(md5sum \$OVE_OWEL_DIR/revtab)
		if [ -e \"${q_remote}\" ]; then
			ove-am ${q_remote} &> /dev/null
			rm ${q_remote}
		fi
		if [ -e \"${o_remote}\" ]; then
			ove-apply-cached ${o_remote} &> /dev/null
			rm ${o_remote}
		fi
		if [ -e \"${p_remote}\" ]; then
			ove-apply ${p_remote} &> /dev/null
			rm ${p_remote}
		fi

		# one extra fetch if revtab was changed
		if [ \"\$md5\" != \"\$(md5sum \$OVE_OWEL_DIR/revtab)\" ] && \
			[ ${fetch} -eq 1 ]; then
			if ove_init; then
				ove-fetch &> /dev/null
			fi
		fi

		if [ ${run_setup} -eq 1 ]; then
			if ! cd ..; then
				exit
			elif [ \${OVE_BASE_DIR##*/} = \${OVE_OWEL_NAME} ]; then
				mv \${OVE_OWEL_NAME} \${OVE_OWEL_NAME}a
				n_base=\${OVE_OWEL_NAME}a
			fi
			if ! mv \${n_base}/{.[!.],}* .; then
				exit
			elif ! rmdir \${n_base}; then
				exit
			fi
		fi"; then
		ret=1
	fi

	if [ $# -eq 1 ]; then
		if [ "${host}" != "localhost" ]; then
			echo -n "${host}:"
		fi
		echo "${d}"
	fi
	if [ -e ${p} ]; then
		${ove_cmd2pathname["rm"]:?} ${p}
	fi
	if [ -e ${q} ]; then
		${ove_cmd2pathname["rm"]:?} ${q}
	fi

	return ${ret}
}

function ove_unittest_preparations {
	local a
	local b
	local f_all
	local i
	local nbr_of_files_per_repo
	local nbr_of_projs
	local nbr_of_repos
	local nbr_of_systests
	local owel_name
	local uuid

	nbr_of_files_per_repo=$1
	nbr_of_projs=$2
	nbr_of_repos=$3
	nbr_of_systests=$4

	echo "${unittest_dir:?}"
	${ove_cmd2pathname["mkdir"]:?} -p ${unittest_dir}/.ove

	if ! cd ${unittest_dir}; then
		return 1
	fi
	${ove_cmd2pathname["ln"]:?} -s ${OVE_SELF} ove
	${ove_cmd2pathname["ln"]:?} -s ${OVE_DIR}/tests .

	# remotes
	${ove_cmd2pathname["mkdir"]:?} -p remotes

	if command -v uuidgen > /dev/null; then
		uuid="$(${ove_cmd2pathname["uuidgen"]:?})"
	elif [ -e /proc/sys/kernel/random/uuid ]; then
		uuid="$(cat /proc/sys/kernel/random/uuid)"
	else
		uuid="$(${ove_cmd2pathname["date"]:?} +%N)"
	fi

	# create some remote bare repos
	for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_repos}) top-${uuid}; do
		${ove_cmd2pathname["mkdir"]:?} -p ${unittest_dir}/remotes/git-${a}
		if ! [ -d .git ]; then
			${ove_cmd2pathname["git"]:?} init -q --bare ${unittest_dir}/remotes/git-${a}
			${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/remotes/git-${a} symbolic-ref HEAD refs/heads/${OVE_DEFAULT_BRANCH_NAME}
		fi
	done

	owel_name="git-top-${uuid}"

	# clone all repositories
	${ove_cmd2pathname["mkdir"]:?} -p testing/src
	for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_repos}); do
		if [ $((a%2)) -eq 0 ]; then
			${ove_cmd2pathname["git"]:?} clone -q remotes/git-${a} ${unittest_dir}/testing/src/git-${a} &> /dev/null
		else
			${ove_cmd2pathname["git"]:?} clone -q remotes/git-${a} ${unittest_dir}/git-${a} &> /dev/null
		fi
	done
	${ove_cmd2pathname["git"]:?} clone -q ${unittest_dir}/remotes/${owel_name} &> /dev/null
	${ove_cmd2pathname["ln"]:?} -s ${owel_name} .owel

	# add some files
	for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_repos}); do
		if [ $((a%2)) -eq 0 ]; then
			if ! cd ${unittest_dir}/testing/src/git-${a}; then
				return 1
			fi
		else
			if ! cd ${unittest_dir}/git-${a}; then
				return 1
			fi
		fi

		f_all=
		for i in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_files_per_repo}); do
			filename=$(echo "${EPOCHREALTIME:?}" | ${ove_cmd2pathname["md5sum"]:?})
			filename=${filename:0:10}
			echo "${filename}" > "${filename}"
			f_all+=" $filename"
		done
		if [ ${nbr_of_files_per_repo} -ne 0 ]; then
			${ove_cmd2pathname["git"]:?} add $f_all
			${ove_cmd2pathname["git"]:?} commit -q -m "asdf"
			${ove_cmd2pathname["git"]:?} checkout -q -b ${OVE_DEFAULT_BRANCH_NAME} 2> /dev/null
			${ove_cmd2pathname["git"]:?} tag 0.0.1
			${ove_cmd2pathname["git"]:?} tag 0.0.2
			${ove_cmd2pathname["git"]:?} tag 0.0.3
			${ove_cmd2pathname["git"]:?} push -q origin ${OVE_DEFAULT_BRANCH_NAME}
			${ove_cmd2pathname["git"]:?} push -q --tags
			${ove_cmd2pathname["git"]:?} branch -q --set-upstream-to=origin/${OVE_DEFAULT_BRANCH_NAME}
		fi
	done

	# create revtab
	for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_repos}); do
		if [ $((a%2)) -eq 0 ]; then
			echo "testing/src/git-${a} ${unittest_dir}/remotes/git-${a} ${unittest_dir}/remotes/git-${a} ${OVE_DEFAULT_BRANCH_NAME}" >> ${unittest_dir}/${owel_name}/revtab
		else
			echo "git-${a} ${unittest_dir}/remotes/git-${a} ${unittest_dir}/remotes/git-${a} ${OVE_DEFAULT_BRANCH_NAME}" >> ${unittest_dir}/${owel_name}/revtab
		fi
	done

	# create projs
	if [ $nbr_of_projs -eq 0 ]; then
		echo "---" > ${unittest_dir}/${owel_name}/projs
	else
		for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_projs}); do
			echo "p${a}:" >> ${unittest_dir}/${owel_name}/projs
			echo -e "  path:\n    .owel" >> ${unittest_dir}/${owel_name}/projs
			if [ ${a} -lt ${nbr_of_projs} ]; then
				echo -e "  deps:\n    p$((a+1))" >> ${unittest_dir}/${owel_name}/projs
			fi
			echo >> ${unittest_dir}/${owel_name}/projs
			${ove_cmd2pathname["mkdir"]:?} -p ${unittest_dir}/${owel_name}/projects/p${a}
			for b in bootstrap configure build install clean; do
				echo "#!${ove_cmd2pathname["bash"]:?}" > ${unittest_dir}/${owel_name}/projects/p${a}/${b}
				echo "echo ${b} p${a}" >> ${unittest_dir}/${owel_name}/projects/p${a}/${b}
				${ove_cmd2pathname["chmod"]:?} +x ${unittest_dir}/${owel_name}/projects/p${a}/${b}
			done

			if [ $a -eq 1 ]; then
				# create a 'l1 -> p1' symlink
				if ! (cd ${unittest_dir}/${owel_name}/projects || exit 1; ${ove_cmd2pathname["ln"]:?} -s p1 l1); then
					return 1
				fi
				# add l1 to 'projs'
				echo -e "l${a}:\n  path:\n    .owel\n\n" >> ${unittest_dir}/${owel_name}/projs
			fi
		done
	fi

	# create systests
	for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_systests}); do
		echo -e "ok${a} 10 0 . true\nnok${a} 10 0 / false\nbg${a} 10 2 / sleep 0.1; true" >> ${unittest_dir}/${owel_name}/systests
	done

	if [ ${nbr_of_systests} -ne 0 ]; then
		# create systests-groups
		echo "all:" >> ${unittest_dir}/${owel_name}/systests-groups
		for a in $(${ove_cmd2pathname["seq"]:?} 1 ${nbr_of_systests}); do
			echo -e "- ok${a}\n- nok${a}\n- bg${a}" >> ${unittest_dir}/${owel_name}/systests-groups
		done
	fi

	# config
	echo "OVE_LOCAL_ECHO 1" > ${unittest_dir}/${owel_name}/.oveconfig
	echo "OVE_LOG_DIR_DISK_USAGE_WARNING_MB 0" >> ${unittest_dir}/${owel_name}/.oveconfig

	# commit and push
	${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/${owel_name} add .
	${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/${owel_name} commit -q -m "test"
	${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/${owel_name} checkout -q -b ${OVE_DEFAULT_BRANCH_NAME} 2> /dev/null
	${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/${owel_name} push -q origin ${OVE_DEFAULT_BRANCH_NAME}
	${ove_cmd2pathname["git"]:?} -C ${unittest_dir}/${owel_name} branch -q --set-upstream-to=origin/${OVE_DEFAULT_BRANCH_NAME}
}

function ove_unittest_exit {
	if [ -e "${OVE_GLOBAL_STATE_DIR}/.oveconfig.bak" ]; then
		${ove_cmd2pathname["mv"]:?} ${OVE_GLOBAL_STATE_DIR}/.oveconfig.bak ${OVE_GLOBAL_STATE_DIR}/.oveconfig
	fi
	if [ -e "${HOME}/.oveconfig.bak" ]; then
		${ove_cmd2pathname["mv"]:?} ${HOME}/.oveconfig.bak ${HOME}/.oveconfig
	fi
}

function ove_unittest_cleanup {
	${ove_cmd2pathname["git"]:?} -C ${OVE_OWEL_DIR} checkout projs revtab &> /dev/null || true
}

function ove_unittest {
	local nbr_of_files_per_repo
	local nbr_of_projs
	local nbr_of_repos
	local nbr_of_systests
	local t
	local tot_files
	local unittest_dir

	nbr_of_files_per_repo=$1
	nbr_of_projs=$2
	nbr_of_repos=$3
	nbr_of_systests=$4

	echo "nbr_of_files_per_repo: ${nbr_of_files_per_repo} nbr_of_projs: ${nbr_of_projs} nbr_of_repos: ${nbr_of_repos} nbr_of_systests: ${nbr_of_systests}"

	unittest_dir="$(mktemp -d -p ${OVE_OWEL_TMP_DIR})"
	if ! ove_unittest_preparations ${nbr_of_files_per_repo} ${nbr_of_projs} ${nbr_of_repos} ${nbr_of_systests}; then
		return 1
	fi

	# 5 = bootstrap configure build install clean
	tot_files=$((nbr_of_files_per_repo * nbr_of_repos + (5 * nbr_of_projs)))

	# one symlink
	if [ $nbr_of_projs -ne 0 ]; then
		((tot_files++))
	fi

	# projs is always there
	((tot_files++))

	# revtab?
	if [ $nbr_of_repos -ne 0 ]; then
		((tot_files++))
	fi

	# systests?
	if [ $nbr_of_systests -ne 0 ]; then
		# systests and systests-groups
		((tot_files+=2))
	fi

	# config
	((tot_files++))

	tot_tests=$((nbr_of_systests * 3))
	if [ $nbr_of_systests -ne 0 ]; then
		((tot_tests+=1))
	fi

	if ! cd ${unittest_dir}; then
		return 1
	fi

	export nbr_of_systests=${tot_tests}
	export nbr_of_projs=${nbr_of_projs}
	export nbr_of_repos=$((nbr_of_repos + 1 ))
	export nbr_of_files=${tot_files}
	for t in $tests; do
		$OVE_DIR/tests/$t
	done

	# cleanup
	${ove_cmd2pathname["rm"]:?} -rf "${unittest_dir:?}"
}

# unittest:[test...]:run all/specific unit tests:INTERNAL
function ove-unittest {
	ove_entry || return

	local a
	local d
	local files
	local i
	local tests

	trap ove_unittest_exit EXIT
	if [ -e "${OVE_GLOBAL_STATE_DIR}/.oveconfig" ]; then
		${ove_cmd2pathname["mv"]:?} ${OVE_GLOBAL_STATE_DIR}/.oveconfig  ${OVE_GLOBAL_STATE_DIR}/.oveconfig.bak
	fi
	if [ -e "${HOME}/.oveconfig" ]; then
		${ove_cmd2pathname["mv"]:?} ${HOME}/.oveconfig ${HOME}/.oveconfig.bak
	fi
	if [ -e "${OVE_CONFIG_FILE_PRIVATE}" ]; then
		${ove_cmd2pathname["rm"]:?} ${OVE_CONFIG_FILE_PRIVATE}
	fi

	ove_echo_cyan "unittest: start"

	if [ $# -eq 0 ]; then
		d="$(${ove_cmd2pathname["mktemp"]:?} -p "${OVE_TMP}" -d)"
		tests="tests/t*.test"

		# tests that depends on nbr_of_systests, nbr_of_projs, nbr_of_repos or nbr_of_files
		${ove_cmd2pathname["git"]:?} \
			-C $OVE_DIR/tests \
			grep \
			-E \
			'nbr_of_systests|nbr_of_projs|nbr_of_repos|nbr_of_files' $OVE_DIR/tests/*.test | \
			${ove_cmd2pathname["cut"]:?} -d':' -f1 | \
			LC_ALL=1 ${ove_cmd2pathname["sort"]:?} -u > "$d"/tests_vars

		# all tests
		${ove_cmd2pathname["find"]:?} ${OVE_DIR}/tests -name '*.test' -exec basename {} \; | LC_ALL=1 ${ove_cmd2pathname["sort"]:?} > $d/tests_all

		# other tests
		LC_ALL=1 ${ove_cmd2pathname["comm"]:?} -1 -3 $d/tests_vars $d/tests_all > $d/tests_other

		# setup what to test
		tests=$(${ove_cmd2pathname["cat"]:?} $d/tests_vars)

		# init output files
		for i in $(seq 1 8); do
			true > $d/unittest_$i
		done

		#            files_per_repo | projs | repos | systest
		ove_unittest       0            0       0        0 >> $d/unittest_1 2>&1 &
		ove_unittest       0            1       0        0 >> $d/unittest_2 2>&1 &
		ove_unittest       1            0       1        0 >> $d/unittest_3 2>&1 &
		ove_unittest       0            0       0        1 >> $d/unittest_4 2>&1 &
		ove_unittest       1            1       1        1 >> $d/unittest_5 2>&1 &
		ove_unittest       2            2       2        2 >> $d/unittest_6 2>&1 &
		ove_unittest       3            3       3        3 >> $d/unittest_7 2>&1 &
		ove_unittest       3           10      10        3 >> $d/unittest_8 2>&1 &

		# setup what to test
		tests=$(${ove_cmd2pathname["cat"]:?} $d/tests_other)
	else
		d="${OVE_TMP}"
		for a in "$@"; do
			if ! [ -e "${OVE_DIR}/tests/${a}.test" ]; then
				continue
			fi
			tests+="${a}.test "
		done

		if [ "${tests}" = "" ]; then
			echo "error: select test(s) from:" 1>&2
			${ove_cmd2pathname["find"]:?} ${OVE_DIR}/tests -name 't*.test' -type f -exec basename {} .test \; | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
			return 1
		fi
	fi

	true > $d/unittest_x
	ove_unittest 3 3 3 3 >> $d/unittest_x 2>&1 &
	wait

	# restore terminal
	${ove_cmd2pathname["stty"]:?} sane
	if [ $# -eq 0 ]; then
		${ove_cmd2pathname["cat"]:?} $d/unittest_{1..8}
		files+="$(echo $d/unittest_{1..8})"
	fi
	${ove_cmd2pathname["cat"]:?} $d/unittest_x
	files+=" $d/unittest_x"
	echo

	# shellcheck disable=SC2016
	i="$(${ove_cmd2pathname["grep"]:?} -h '^Ran [0-9]\+ test' $files | \
			${ove_cmd2pathname["grep"]:?} -o '[0-9]\+' | \
			${ove_cmd2pathname["awk"]:?} '{s+=$1} END {print s}')"

	if ! ${ove_cmd2pathname["grep"]:?} -q -E 'shunit.*|FAILED.*' $files; then
		ove_echo_green "all ${i} test(s) ran OK."
		return 0
	else
		ove_echo_red "ran ${i} test(s). Failures:"
		${ove_cmd2pathname["grep"]:?} --color=always -E -H -n 'shunit.*|FAILED.*' $files
		return 1
	fi
}

# less-lastlog:[user...]:peek into user(s) last OVE log using less:LOG
function ove-less-lastlog {
	ove_entry || return

	ove_watch_logs "less" "$@"
}

# tail-lastlog:[user...]:peek into user(s) last OVE log using tail -f:LOG
function ove-tail-lastlog {
	ove_entry || return

	ove_watch_logs "tail" "$@"
}

# $1: tail|less
# ${@:2}: users
function ove_watch_logs {
	local cmd
	local cmdline
	local cmdpathname
	local d
	local e
	local i
	local ignore
	local log
	local u
	local users

	cmd=$1
	if [ "${cmd}" = "tail" ]; then
		cmdpathname="${ove_cmd2pathname["tail"]:?}"
	elif [ "${cmd}" = "less" ]; then
		cmdpathname="${ove_cmd2pathname["less"]:?}"
	else
		return 1
	fi
	shift

	if [ -d /var/tmp ]; then
		d="/var/tmp"
	else
		d="/tmp"
	fi

	if [ $# -eq 0 ]; then
		e+="./*/ove/logs"
	else
		for u in "$@"; do
			if [ ! -d ${d}/${u}/ove/logs ]; then
				continue
			fi
			e+="./${u}/ove/logs "
		done
	fi

	if [ "${e}" = "" ]; then
		ove_echo_error_noprefix "no logs found for user(s): $*"
		return 1
	fi

	# shellcheck disable=SC2164
	mapfile -t users < <(cd ${d}; ${ove_cmd2pathname["find"]:?} ${e} -maxdepth 0 -type d | ${ove_cmd2pathname["cut"]:?} -d/ -f2)
	if [ "${users[*]}" = "" ]; then
		ove_echo_error_noprefix "no logs found for user(s): $*"
		return 1
	fi

	ignore="tail-lastlog|less-lastlog"
	if ove_sanity_check_tmux 2> /dev/null; then
		for u in "${users[@]}"; do
			log=$(${ove_cmd2pathname["find"]:?} ${d}/${u}/ove/logs/current/ -type f -name "*-ove-*.log" 2> /dev/null | \
				${ove_cmd2pathname["grep"]:?} -v -E "${ignore}" | \
				LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
				${ove_cmd2pathname["tail"]:?} -1)
			if [ "${log}" = "" ]; then
				ove_echo_error_noprefix "no logs found for user: ${u}"
				continue
			fi

			cmdline=
			if [ "${cmd}" = "less" ] && [ "${OVE_LESS_MORE_OPTIONS}" -eq 1 ]; then
				cmdline="${cmdpathname} -R -Ps\"${log//./\\.}\""
			elif [ "${cmd}" = "less" ]; then
				cmdline="${cmdpathname} -R"
			else
				if [ -h "${d}/${u}/ove/logs/ongo" ]; then
					log="${d}/${u}/ove/logs/ongo"
				fi
				cmdline="${cmdpathname} -f -s 0.1 -q -F"
			fi

			${ove_cmd2pathname["tmux"]:?} split-window -h "${cmdline} ${log} 2> /dev/null"
			if [ $# -eq 1 ]; then
				return
			fi
			${ove_cmd2pathname["tmux"]:?} select-layout ${OVE_TMUX_LAYOUT}
		done

		return
	fi

	# not TMUX
	if [ ${#users[*]} -eq 1 ]; then
		u=${users[0]}
	else
		i=1
		for u in "${users[@]}"; do
			echo "$i:$u"
			((i++))
		done
		read -r -p "user: "
		if ! [[ "${REPLY}" =~ ^[0-9]+$ ]] || [ "${REPLY}" -gt ${#users[*]} ]; then
			return 1
		fi
		echo
		u=${users[$((REPLY - 1))]}
	fi

	if ! [ -d "${d}/${u}" ]; then
		ove_echo_error_noprefix "no logs found for user: ${u}"
		return 1
	fi

	log=$(${ove_cmd2pathname["find"]:?} ${d}/${u}/ove/logs/current/ -type f -name "*-ove-*.log" 2> /dev/null | \
		${ove_cmd2pathname["grep"]:?} -v -E "${ignore}" | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
		${ove_cmd2pathname["tail"]:?} -1)
	if [ "${log}" = "" ]; then
		ove_echo_error_noprefix "no logs found for user: ${u}"
		return 1
	fi

	if [ "${cmd}" = "less" ] && [ "${OVE_LESS_MORE_OPTIONS}" -eq 1 ]; then
		cmdline="${cmdpathname} -R -Ps\"${log//./\\.}\""
	elif [ "${cmd}" = "less" ]; then
		cmdline="${cmdpathname} -R"
	else
		if [ -h "${d}/${u}/ove/logs/ongo" ]; then
			log="${d}/${u}/ove/logs/ongo"
		fi
		cmdline="${cmdpathname} -f -s 0.1 -q -F"
	fi

	eval ${cmdline} ${log} 2> /dev/null
}

# remove-repo:name...:remove repo(s) from 'revtab':CORE
function ove-remove-repo {
	ove_entry || return
	ove_revtab_sanity || return

	local e=0
	local r
	local repos

	if [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	repos=$(ove_validate_repo_list "$@")
	if [ "${repos}" = "" ]; then
		ove_echo_error_noprefix "invalid repo name(s): ${*}"
		return 1
	fi

	for r in ${repos}; do
		if [ "${r}" = "${OVE_OWEL_NAME}" ]; then
			ove_echo_error_noprefix "not possible to remove '${OVE_OWEL_NAME}'"
			((e++))
			continue
		elif ! ${ove_cmd2pathname["sed"]:?} -i -e "\,^${r} ,d" "${OVE_OWEL_DIR}/revtab"; then
			ove_echo_fatal_noprefix "removing '$r' from '${OVE_OWEL_DIR}/revtab' failed"
			((e++))
			return $e
		fi
	done

	return $e
}

# add-repo:dir|url|url name|url name rev:add a new repo to this OVE workspace:CORE
function ove-add-repo {
	ove_entry || return

	local fetch_url
	local name
	local p
	local push_url
	local remote
	local revision

	if [ $# -eq 0 ] || [ $# -gt 3 ]; then
		ove_command_usage
		return 1
	fi

	name="${1}"
	if [ ${#name} -ne 1 ]; then
		# remove trailing slash
		name="${name%/}"
	fi

	if [ $# -eq 1 ] && ove_dir_is_repo "${name}"; then
		# sanity check
		if [ "$(ove_validate_repo_list "$name")" != "" ]; then
			ove_echo_error_noprefix "'$name' is already added"
			return 1
		fi

		# multiple remotes?
		if [ $(ove_get_nbr_of_remotes "${name}") -gt 1 ]; then
			ove_echo_cyan_noprefix "select one remote for '${name}'"
			${ove_cmd2pathname["git"]:?} -C "${name}" remote -v
			while true; do
				read -r -p "remote: "
				remote="${REPLY}"
				if ${ove_cmd2pathname["git"]:?} -C "${name}" remote | ${ove_cmd2pathname["grep"]:?} -q ^${remote}$; then
					break;
				fi
			done
		else
			remote=$(${ove_cmd2pathname["git"]:?} -C "${name}" remote)
		fi

		fetch_url=$(ove_get_fetch_url "${name}" ${remote})
		push_url=$(ove_get_push_url "${name}" ${remote})
		revision=$(ove_get_revision "${name}")
	else
		fetch_url="${name}"
		push_url="${fetch_url}"
		revision="${OVE_DEFAULT_BRANCH_NAME}"

		if [ $# -eq 1 ]; then
			name="${name##*/}"
			name="${name%%.*}"

			read -r -p "name? (leave empty to name it '${name}'): "
			if [ "${REPLY}" != "" ]; then
				name="${REPLY}"
			fi
		elif [ $# -eq 2 ]; then
			name="${2}"
		elif [ $# -eq 3 ]; then
			name="${2}"
			revision="${3}"
		fi

		# sanity check
		if [ "$(ove_validate_repo_list "$name")" != "" ]; then
			ove_echo_error_noprefix "'$name' is already added"
			return 1
		fi

		if [ $# -eq 1 ] || [ $# -eq 2 ]; then
			read -r -p "revision? (leave empty to use '${revision}'): "
			if [ "${REPLY}" != "" ]; then
				revision="${REPLY}"
			fi
		fi
	fi

	# update revtab
	echo "${name} ${fetch_url} ${push_url} ${revision}" >> "${OVE_OWEL_DIR}/revtab"

	# parse revtab
	if ! ove_revtab_init; then
		# remove last line
		${ove_cmd2pathname["sed"]:?} -i '$ d' "${OVE_OWEL_DIR}/revtab"
		return 1
	elif [ ! -d "${name}" ] && ! ove-fetch "${name}"; then
		return 1
	fi

	# import projects
	if [ "${OVE_IMPORT_PROJECTS}" != "0" ] && [ -d ${OVE_BASE_DIR}/${name}/.ove ]; then
		if [ "${OVE_IMPORT_PROJECTS}" != "1" ] && [ "${OVE_IMPORT_PROJECTS}" != "2" ]; then
			ove_echo_warning_noprefix "invalid value '${OVE_IMPORT_PROJECTS}' for config 'OVE_IMPORT_PROJECTS'"
		else
			for p in $(${ove_cmd2pathname["find"]:?} ${OVE_BASE_DIR}/${name}/.ove -maxdepth 1 -mindepth 1 -type f -name '*.tar.bz2'); do
				if [ "${OVE_IMPORT_PROJECTS}" = "2" ]; then
					# display list of projects
					${ove_cmd2pathname["tar"]:?} tf "${p}" --wildcards '*.patch' | \
						${ove_cmd2pathname["sed"]:?} -e '/common.patch/d' -e 's,\.patch$,,g' -e 's,^\.\/,,g' | \
						LC_ALL="C" ${ove_cmd2pathname["sort"]:?} | \
						${ove_cmd2pathname["cat"]:?} -n
					read -p "import project(s) from '${p}'? (y/N) " -r
					if [[ ! ${REPLY} =~ ^[Yy]$ ]]; then
						continue
					fi
				fi
				ove-import "${p}" || true
			done
		fi
	fi

	return 0
}

# add-project:[name path]|[name path cmd...]|[name path cmd@content...]:add one project to 'projs' and 'projects/...':CORE
function ove-add-project {
	ove_entry || return

	local c
	local cmd
	local content
	local deps
	local i
	local j
	local name
	local name_check_ok
	local needs
	local needs_dist
	local path
	local proj_dir
	local tags

	if [ $# -eq 1 ]; then
		ove_command_usage
		return 1
	elif [ $# -ge 2 ]; then
		name="$1"

		if ! ove_project_validate_name ${name}; then
			ove_echo_error_noprefix "project name '${name}' is not allowed"
			return 1
		fi

		path="$2"
		proj_dir="$OVE_OWEL_DIR/projects/${name}"
		if ! ${ove_cmd2pathname["mkdir"]:?} -p ${proj_dir}; then
			ove_echo_fatal_noprefix "'mkdir -p ${proj_dir}' failed"
			return 1
		fi

		shift 2
		for c in "$@"; do
			if [[ ${c} == *@* ]]; then
				cmd=${c%%@*}
				content="${c#*@}"
				if [ "${cmd}" = "" ]; then
					ove_echo_error_noprefix "format error: ${c}"
					continue
				fi
			else
				cmd=${c}
			fi

			if [ "${cmd}" = "name" ] || [ "${cmd}" = "path" ]; then
				ove_echo_error_noprefix "reserved word: ${cmd}"
				continue
			fi

			if [[ ${c} != *@* ]]; then
				while true; do
					read -p "$(printf "%-9s" ${cmd}): " -r
					if [ "$REPLY" = "" ]; then
						continue
					fi
					content="$REPLY"
					break
				done
			fi

			if [ "${cmd}" = "deps" ] || [ "${cmd}" = "needs" ] || [ "${cmd}" = "tags" ]; then
				if [ -v ${cmd} ]; then
					eval ${cmd}="\"${!cmd} ${content}\""
				else
					eval local ${cmd}="\"${content}\""
				fi
				continue
			elif [[ "${cmd}" = needs_* ]]; then
				if [ -v ${cmd} ]; then
					eval ${cmd}="\"${!cmd} ${content}\""
				else
					eval local ${cmd}="\"${content}\""
					needs_dist+=" $cmd"
				fi
				continue
			fi
			echo -e "${content}" > ${proj_dir}/${cmd}
			if ! ${ove_cmd2pathname["chmod"]:?} +x ${proj_dir}/${cmd}; then
				ove_echo_fatal_noprefix "'chmod +x ${proj_dir}/${cmd}' failed"
				return 1
			fi
		done

	else
		name_check_ok=0
		for c in name path deps needs tags bootstrap configure build install clean test; do
			while true; do
				read -p "$(printf "%-9s" ${c}): " -r
				if [ "${c}" = "name" ] || [ "${c}" = "path" ]; then
					if [ "$REPLY" = "" ]; then
						continue
					fi

					if [ "${c}" = "name" ]; then
						if [ $name_check_ok -eq 0 ] && ! ove_project_validate_name "${REPLY}"; then
							ove_echo_error_noprefix "project name '${REPLY}' is not allowed"
							continue
						fi
						name_check_ok=1
					fi
					eval local ${c}="$REPLY"
					continue 2
				elif [ "${c}" = "deps" ] || [ "${c}" = "needs" ] || [ "${c}" = "tags" ]; then
					if [ "$REPLY" = "" ]; then
						echo -en "\033[1A\033[2K"
					else
						eval local ${c}="$REPLY"
					fi
					continue 2
				elif [ "$REPLY" = "" ]; then
					echo -en "\033[1A\033[2K"
					continue 2
				fi
				break
			done

			if [ "${c}" = "path" ] || [ "${c}" = "deps" ] || [ "${c}" = "needs" ] || [ "${c}" = "tags" ]; then
				continue
			fi

			proj_dir="$OVE_OWEL_DIR/projects/${name}"

			if ! ${ove_cmd2pathname["mkdir"]:?} -p ${proj_dir}; then
				ove_echo_fatal_noprefix "'mkdir -p ${proj_dir}' failed"
				return 1
			fi

			echo "$REPLY" > ${proj_dir}/${c}
			if ! ${ove_cmd2pathname["chmod"]:?} +x ${proj_dir}/${c}; then
				ove_echo_fatal_noprefix "'chmod +x ${proj_dir}/${c}' failed"
				return 1
			fi
		done
	fi

	if [ -s $OVE_OWEL_DIR/projs ] && ${ove_cmd2pathname["grep"]:?} -q ${name}: $OVE_OWEL_DIR/projs; then
		ove_echo_note_noprefix "project '${name}' is already present in '$OVE_OWEL_DIR/projs':"
		${ove_cmd2pathname["grep"]:?} -H -n -A3 --color=always "${name}:" $OVE_OWEL_DIR/projs | ${ove_cmd2pathname["sed"]:?} -e "s,$OVE_BASE_DIR/,,g"
	else
		if [ -s $OVE_OWEL_DIR/projs ]; then
			echo >> $OVE_OWEL_DIR/projs
		else
			echo "---" >> $OVE_OWEL_DIR/projs
		fi
		echo -e "${name}:\n  path:\n    ${path}" >> $OVE_OWEL_DIR/projs

		if [ "${deps}" != "" ]; then
			echo -e "  deps:" >> $OVE_OWEL_DIR/projs
			while read -r i; do
				echo "    $i" >> $OVE_OWEL_DIR/projs
			done < <(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"$(printf "%s\n" ${deps})")
		fi

		if [ "${needs}" != "" ]; then
			echo -e "  needs:" >> $OVE_OWEL_DIR/projs
			while read -r i; do
				echo "    $i" >> $OVE_OWEL_DIR/projs
			done < <(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"$(printf "%s\n" ${needs})")
		fi

		if [ "${tags}" != "" ]; then
			echo -e "  tags:" >> $OVE_OWEL_DIR/projs
			while read -r i; do
				echo "    $i" >> $OVE_OWEL_DIR/projs
			done < <(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"$(printf "%s\n" ${tags})")
		fi

		if [ "${needs_dist}" != "" ]; then
			for i in ${needs_dist}; do
				echo -e "  $i:" >> $OVE_OWEL_DIR/projs
				while read -r j; do
					echo "    $j" >> $OVE_OWEL_DIR/projs
				done < <(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <<<"$(printf "%s\n" ${!i})")
			done
		fi
	fi

	if [ "${proj_dir}" != "" ]; then
		ove_reinit
		ove-list-projects ${name}
	fi
}

# generate-doc: :generate OVE documentation:INTERNAL
function ove-generate-doc {
	ove_entry || return

	local a
	local b
	local c
	local d
	local funcs
	local header
	local sorted
	local str
	local sum

	# ove-cmd-list.md (command list)
	a=$(${ove_cmd2pathname["grep"]:?} -B1 "^function ove-" "${OVE_BASE_DIR}"/ove | \
		${ove_cmd2pathname["grep"]:?} '#' | \
		${ove_cmd2pathname["cut"]:?} -b3-)
	b=$(set | \
		${ove_cmd2pathname["grep"]:?} ove_plugin_helptext | \
		${ove_cmd2pathname["grep"]:?} -v '\$'| \
		${ove_cmd2pathname["cut"]:?} -d'"' -f2 | \
		${ove_cmd2pathname["grep"]:?} -v -f<(printf "%s\n" ${OVE_SCRIPTS_LIST} | ${ove_cmd2pathname["sed"]:?} -e 's|^|^|g' -e 's|$|:|g'))

	header="| Command:| Arguments:| Description:| Category: |"
	sorted=$(printf "${a}\n${b}" | \
		${ove_cmd2pathname["sed"]:?} \
		-e 's/|/#/g' \
		-e 's/:/ :| /g' \
		-e 's/^/| /g' \
		-e 's/$/: |/g' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?})

	${ove_cmd2pathname["mkdir"]:?} -p "${OVE_DIR}"/doc
	printf "${header}\n|-|-|-|-|\n${sorted}\n" | \
		${ove_cmd2pathname["sed"]:?} -e 's/\#/\\|/g' | \
		${ove_cmd2pathname["column"]:?} -s: -t | \
		${ove_cmd2pathname["sed"]:?} 's/[ \t]*$//' \
		> ${OVE_DIR}/doc/ove-cmd-list.md

	# ove-config-list.md (configuration list)
	for c in $(type ove_config_builtins_init | ${ove_cmd2pathname["grep"]:?} -o 'OVE_[A-Z_0-9]\+'| LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -u); do
		str+="$(${ove_cmd2pathname["grep"]:?} -o "# ${c}:.*:.*" ${OVE_SELF} | ${ove_cmd2pathname["cut"]:?} -b3-):$(type ove_config_builtins_init | \
			${ove_cmd2pathname["grep"]:?} "export ${c}=" | \
			${ove_cmd2pathname["cut"]:?} -d= -f2- | \
			${ove_cmd2pathname["sed"]:?} -e 's,;$,,g' | \
			${ove_cmd2pathname["tr"]:?} -d '"')\n"
	done
	sorted=$(printf "${str}" | \
		${ove_cmd2pathname["sed"]:?} \
		-e 's/|/#/g' \
		-e 's/:/ :| /g' \
		-e 's/^/| /g' \
		-e 's/$/: |/g' | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?})

	header="| Config:| Type: | Allowed:| Affect: | Description: | Default value:"
	printf "${header}\n|-|-|-|-|-|-|\n${sorted}\n" | \
		${ove_cmd2pathname["sed"]:?} -e 's/\#/\\|/g' | \
		${ove_cmd2pathname["column"]:?} -s: -t | \
		${ove_cmd2pathname["sed"]:?} 's/[ \t]*$//' \
		> ${OVE_DIR}/doc/ove-config-list.md

	# ove.bash
	${ove_cmd2pathname["sed"]:?} -i "s/^ove_built_ins=.*/ove_built_ins=\"$(ove_get_built_ins)\"/g" ${OVE_DIR}/ove.bash

	# ove.static
	echo "OVE_BUILT_INS=\"$(ove_get_built_ins)\"" >${OVE_DIR}/ove.static
	echo "export OVE_BUILT_INS" >>${OVE_DIR}/ove.static
	funcs=$(${ove_cmd2pathname["grep"]:?} -B1 '^function ove-' ${OVE_SELF})
	str=$(${ove_cmd2pathname["grep"]:?} ': :' <<< "${funcs}" | \
		${ove_cmd2pathname["cut"]:?} -b3- | \
		${ove_cmd2pathname["cut"]:?} -d: -f1 | \
		LC_ALL="C" ${ove_cmd2pathname["sort"]:?})
	str=${str//$'\n'/ }
	echo "OVE_BUILT_INS_WITHOUT_ARGS=\"${str}\"" >>${OVE_DIR}/ove.static
	echo "export OVE_BUILT_INS_WITHOUT_ARGS" >>${OVE_DIR}/ove.static

	# ove-variables-list.md (variables with descriptions)
	# shellcheck disable=SC2016
	a=$(ove-env | ${ove_cmd2pathname["awk"]:?} '{print $1}')
	# shellcheck disable=SC2016
	b=$(${ove_cmd2pathname["grep"]:?} OVE_ ${OVE_DIR}/doc/ove-config-list.md | ${ove_cmd2pathname["awk"]:?} '{print $2}')
	str=
	header="| Variable:| Description:"
	for c in $(LC_ALL="C" ${ove_cmd2pathname["comm"]:?} -3 \
		<(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} \
		<(printf "%s" "$a")) <(LC_ALL="C" ${ove_cmd2pathname["sort"]:?} <(printf "%s" "$b"))); do
		d=$(${ove_cmd2pathname["grep"]:?} "# $c:" $OVE_SELF | ${ove_cmd2pathname["cut"]:?} -d':' -f2-)
		if [ "$d" != "" ]; then
			str+="| $c:| $d:|\n"
		fi
	done

	printf "$header\n|-|-|\n$str" | \
		${ove_cmd2pathname["column"]:?} -s: -t | \
		${ove_cmd2pathname["sed"]:?} 's/[ \t]*$//' \
		> ${OVE_DIR}/doc/ove-variables-list.md

	# ove-externals-list.md (external commands and usage)
	header="| Command:| Usage:|"
	str=
	sum=0
	# shellcheck disable=SC2016
	while read -r a b; do
		str+="| $a:| $b:|\n"
		sum=$((sum + b))
	done <<<"$(ove-list-externals | \
		${ove_cmd2pathname["awk"]:?} '{print $1,$5}')"
	printf "$header\n| ---:| ---:|\n$str| __sum__:| __${sum}__:|\n" | \
	${ove_cmd2pathname["column"]:?} -s: -t > ${OVE_DIR}/doc/ove-externals-list.md

	return 0
}

# shell-check: :run shellcheck on OVE:INTERNAL
function ove-shell-check {
	ove_entry || return

	local exclude

	if ! ove_check_command "shellcheck"; then
		return 1
	fi

	# this {/} is literal...
	exclude+="SC1083,"

	# can't follow non-constant source
	exclude+="SC1090,"

	# not following
	exclude+="SC1091,"

	# Modification of var is local (to subshell caused by pipeline)
	exclude+="SC2030,"

	# var was modified in a subshell. That change might be lost.
	exclude+="SC2031,"

	# quote this to prevent word splitting
	exclude+="SC2046,"

	# don't use variables in the printf format string. Use printf
	exclude+="SC2059,"

	# double quote to prevent globbing and word splitting
	exclude+="SC2086,"

	# use foo "$@" if function's $1 should mean script's $1
	exclude+="SC2119,"

	# foo references arguments, but none are ever passed
	exclude+="SC2120"

	cd "${OVE_DIR:?}" || return 1
	while read -r f; do
		# run shellcheck
		(cd "${OVE_DIR}" && ${ove_cmd2pathname["shellcheck"]:?} -e ${exclude} "${f}")
		# tabs and spaces
		ove_validate_tabs_and_space "${f}"
	done < <(${ove_cmd2pathname["git"]:?} -C ${OVE_DIR} ls-files -- ":(exclude)${OVE_BASENAME}" | ${ove_cmd2pathname["xargs"]:?} file | ${ove_cmd2pathname["grep"]:?} 'shell script' | ${ove_cmd2pathname["cut"]:?} -d: -f1)

	# then, run shellcheck on self
	(cd "${OVE_DIR}" && \shellcheck --extended-analysis=false -x -e ${exclude} "${OVE_SELF}" > "${OVE_TMP}/shell-check")
	if [ ! -s "${OVE_TMP}/shell-check" ]; then
		return 0
	fi

	${ove_cmd2pathname["cat"]:?} "${OVE_TMP}/shell-check"
	return 1
}

function ove_externals_reinit {
	unset ove_cmd2pathname
	ove_externals_init
}

function ove_externals_init {
	local cmds=()
	local cmd
	local pathname
	local _kernel
	local restore

	if declare -p ove_cmd2pathname &> /dev/null; then
		return
	fi

	cmds+=('ag')
	cmds+=('awk')
	cmds+=('basename')
	cmds+=('bash')
	cmds+=('cat')
	cmds+=('chmod')
	cmds+=('column')
	cmds+=('comm')
	cmds+=('convert')
	cmds+=('cp')
	cmds+=('csplit')
	cmds+=('cut')
	cmds+=('date')
	cmds+=('diff')
	cmds+=('dig')
	cmds+=('dirname')
	cmds+=('dot')
	cmds+=('du')
	cmds+=('ffmpeg')
	cmds+=('file')
	cmds+=('find')
	cmds+=('flock')
	cmds+=('fold')
	cmds+=('fzf')
	cmds+=('gcc')
	cmds+=('getconf')
	cmds+=('git')
	cmds+=('graph-easy')
	cmds+=('grep')
	cmds+=('head')
	cmds+=('incus')
	cmds+=('inotifywait')
	cmds+=('jp2a')
	cmds+=('ld')
	cmds+=('less')
	cmds+=('ln')
	cmds+=('locate')
	cmds+=('lsb_release')
	cmds+=('lxc')
	cmds+=('make')
	cmds+=('md5deep')
	cmds+=('md5sum')
	cmds+=('mkdir')
	cmds+=('mktemp')
	cmds+=('mv')
	cmds+=('pgrep')
	cmds+=('ps')
	cmds+=('pstree')
	cmds+=('readlink')
	cmds+=('recordmydesktop')
	cmds+=('rev')
	cmds+=('rg')
	cmds+=('rm')
	cmds+=('rmdir')
	cmds+=('scp')
	cmds+=('script')
	cmds+=('scriptreplay')
	cmds+=('sed')
	cmds+=('seq')
	cmds+=('setsid')
	cmds+=('shellcheck')
	cmds+=('sleep')
	cmds+=('sort')
	cmds+=('ssh')
	cmds+=('stat')
	cmds+=('stty')
	cmds+=('su')
	cmds+=('sudo')
	cmds+=('sync')
	cmds+=('tac')
	cmds+=('tail')
	cmds+=('tar')
	cmds+=('task')
	cmds+=('tee')
	cmds+=('timeout')
	cmds+=('tmux')
	cmds+=('touch')
	cmds+=('tr')
	cmds+=('tsort')
	cmds+=('tsp')
	cmds+=('uname')
	cmds+=('uniq')
	cmds+=('uuidgen')
	cmds+=('wc')
	cmds+=('whoami')
	cmds+=('whois')
	cmds+=('xargs')
	cmds+=('xdotool')
	cmds+=('yamllint')

	declare -g -A ove_cmd2pathname

	restore=0

	if shopt -q expand_aliases; then
		shopt -u expand_aliases
		restore=1
	fi
	for cmd in "${cmds[@]}"; do
		unset -f $cmd
		if ! pathname=$(command -v ${cmd}); then
			continue
		fi

		ove_cmd2pathname["$cmd"]="${pathname}"
	done
	if [ $restore -eq 1 ]; then
		shopt -s expand_aliases
	fi

	_kernel=$(\uname -o)
	if [[ "${_kernel,,}" == *bsd* ]]; then
		ove_cmd2pathname["head"]="$(command -v ghead)"
		ove_cmd2pathname["tac"]="$(command -v gtac)"
		ove_cmd2pathname["make"]="$(command -v gmake)"
	fi
}

# $1: cmd
function ove_external_version {
	local v
	local ver

	# special treatment
	if [[ "$1" == *tmux ]] || [[ "$1" == *ssh ]]; then
		ver=$(${ove_cmd2pathname["timeout"]:?} 1 $1 -V 2>&1 | ${ove_cmd2pathname["head"]:?} -1)
		echo "$ver"
		return
	fi

	for v in --version -v -V; do
		ver=$(${ove_cmd2pathname["timeout"]:?} 1 $1 $v 2> /dev/null | ${ove_cmd2pathname["head"]:?} -1)
		if [ "$ver" = "" ]; then
			continue
		fi
		echo "$ver"
		return
	done

	return 1
}

# list-externals: :list all external commands that OVE is dependent on:CORE
function ove-list-externals {
	ove_entry || return

	local cmd
	local cnt
	local md5
	local ver

	for cmd in "${!ove_cmd2pathname[@]}"; do
		md5="$(${ove_cmd2pathname["md5sum"]:?} $(${ove_cmd2pathname["readlink"]:?} -f -- ${ove_cmd2pathname[$cmd]}))"
		ver="$(ove_external_version ${ove_cmd2pathname[$cmd]:?})"
		cnt="$(${ove_cmd2pathname["grep"]:?} -c "\${ove_cmd2pathname\[\"$cmd\"\]" ${OVE_SELF})"
		echo "${cmd}@${ove_cmd2pathname[$cmd]}@${md5}@${cnt}@${ver}"
	done | ${ove_cmd2pathname["column"]:?} -t -s@ | LC_ALL="C" ${ove_cmd2pathname["sort"]:?}
}

# nop: :do nothing:DEBUG
function ove-nop {
	ove_entry || return

	:
}

# rename:[new]:rename OWEL/workspace, USE WITH CARE:CORE
function ove-rename {
	ove_entry || return

	local a
	local aa
	local b
	local bb
	local c
	local cur
	local link
	local new
	local resolved

	if [ $# -gt 1 ]; then
		ove_command_usage
		return 1
	fi

	cur="${OVE_OWEL_NAME}"
	if [ $# -eq 1 ]; then
		new="$1"
	else
		echo "current: ${cur}"
		read -r -p "new name: "
		if [ "${REPLY}" = "" ]; then
			return
		fi
		new="${REPLY}"
	fi

	# sanity checks
	if [ "${new}" = "" ] || [ "${new}" = "${cur}" ]; then
		return 1
	elif [ -e "${new}" ]; then
		ove_echo_error_noprefix "'${new}' exists"
		return 1
	elif [[ "${new}" =~ [^a-zA-Z0-9_-] ]]; then
		ove_echo_error_noprefix "the name '${new}' is not allowed. Try: a-zA-Z0-9_-"
		return 1
	elif ${ove_cmd2pathname["grep"]:?} -q -w "${new}" <<<"archives ove stage tmp var ${OVE_USER}"; then
		ove_echo_error_noprefix "'${new}' is a reserved word"
		return 1
	elif ove_uniq $(printf "%s\n" $(ove_revtab_list_basename) | ${ove_cmd2pathname["cut"]:?} -d/ -f1) | ${ove_cmd2pathname["grep"]:?} -q "^${new}$"; then
		ove_echo_error_noprefix "'${new}' clash with a repo name in '${OVE_OWEL_DIR}/revtab'"
		return 1
	fi

	if ! cd ${OVE_BASE_DIR}; then
		return 1
	fi
	for link in .owel .ove.state .ove.tmp README; do
		resolved="$(${ove_cmd2pathname["readlink"]:?} ${link})"
		if [[ "${resolved}" != *${cur}* ]]; then
			continue
		fi

		if [ -d "${resolved}" ]; then
			if [[ "${resolved}" = */tmp/* ]]; then
				# special treatment for .ove.state and .ove.tmp
				a="${resolved%/*}"
				b="${a%/*}/${new}"
				aa="${OVE_USER}/ove/${cur}"
				bb="${OVE_USER}/ove/${new}"
				c="${resolved/${aa}/${bb}}"
			else
				a="${resolved%%"${cur}"*}${cur}"
				b="${resolved%%"${cur}"*}${new}"
				c="${resolved/${cur}/${new}}"
			fi
			${ove_cmd2pathname["mv"]:?} "${a}" "${b}"
		fi
		${ove_cmd2pathname["rm"]:?} "${link}"
		${ove_cmd2pathname["ln"]:?} -s "${c}" "${link}"
	done
}

function ove_distrocheck_helper {
	local d
	local pattern
	local proj

	if [ $# -lt 2 ]; then
		return 1
	elif [ ! -s ${OVE_GLOBAL_STATE_DIR:?}/distrocheck.images ] && ! ove-refresh-image; then
		return 1
	fi

	proj="$1"
	if [[ -v ove_projects_name2index[${proj}] ]]; then
		if ! ove_project_has_step "${proj}" "distcheck"; then
			ove_echo_error_noprefix "$proj does not have a distcheck file '\${OVE_OWEL_DIR}/projects/${proj}/distcheck'. Add one and retry!"
			return 1
		fi

		OVE_DISTROCHECK_STEPS+=" ove"
	fi

	if [ $# -eq 2 ]; then
		pattern="$2"
	else
		shift
		pattern="'"
		while true; do
			pattern+="$1|"
			shift
			if [ $# -eq 0 ]; then
				break
			fi
		done
		pattern="${pattern::-1}'"
	fi

	mapfile -t distro_list <<<"$(eval ${ove_cmd2pathname["grep"]:?} -E "$pattern" "${OVE_GLOBAL_STATE_DIR}/distrocheck.images")"
	if [[ ( ${#distro_list[@]} -eq 0 ) || ( ${#distro_list[@]} -eq 1 && "${distro_list[*]}" = "" ) ]]; then
		ove_echo_error_noprefix "try another filter, choose from:"
		${ove_cmd2pathname["sleep"]:?} 1
		${ove_cmd2pathname["cat"]:?} -n ${OVE_GLOBAL_STATE_DIR:?}/distrocheck.images
		return 1
	fi

	if [[ "$OVE_DISTROCHECK_STEPS" == *verbose* ]]; then
		for d in "${distro_list[@]}"; do
			echo "$d"
		done
	fi
}

# distrocheck:file|project pattern...:verify a project within multiple Linux distributions (incus|LXD only):UTIL
function ove-distrocheck {
	ove_entry || return

	local d
	local distro_list

	if ! ove_distrocheck_helper "$@"; then
		ove_command_usage
		return 1
	fi

	for d in "${distro_list[@]}"; do
		${OVE_DIR}/distrocheck "${1}" "$d"
	done
}

# distrocheck-parallel:file|project pattern...:distrocheck in parallel (tmux and incus|LXD only):UTIL
function ove-distrocheck-parallel {
	ove_entry || return

	local args
	local d
	local distro_list
	local env
	local v
	local val

	if ! ove_sanity_check_tmux; then
		ove_command_usage
		return 1
	elif ! ove_distrocheck_helper "$@"; then
		ove_command_usage
		return 1
	fi

	if [ -v OVE_UNITTEST_TC ]; then
		env+=" OVE_UNITTEST_TC=${OVE_UNITTEST_TC}"
	fi

	for v in $(compgen -A variable OVE_DISTROCHECK_); do
		val=${!v}
		env+=" $v=${val// /:}"
	done

	for d in "${distro_list[@]}"; do
		args+=" 0 '$env ${OVE_DIR}/distrocheck $1 $d'"
	done

	eval ove-run-parallel $args
}

# distrocheck-all:pattern...:distrocheck ALL projects within one or multiple Linux distributions (incus|LXD only):UTIL
function ove-distrocheck-all {
	ove_entry || return

	local c
	local cmd
	local p

	if ! c=$(ove_container_command); then
		return 1
	elif [ $# -eq 0 ]; then
		ove_command_usage
		return 1
	fi

	cmd="ove-distrocheck"
	if ove_sanity_check_tmux 2> /dev/null; then
		cmd+="-parallel"
	fi

	# random order
	for p in $(printf "%s\n" $OVE_PROJECT_LIST | LC_ALL="C" ${ove_cmd2pathname["sort"]:?} -R); do
		OVE_DISTROCHECK_CONTAINER_PREFIX="${p//_/-}" "${cmd}" "$p" "$@"
	done
}

# pre-push: :shell-check+unittest+generate-doc combo:INTERNAL
function ove-pre-push {
	ove_entry || return

	if ! ove_validate_self; then
		return 1
	fi

	if [ -d ${OVE_OWEL_TMP_DIR}/unittest ]; then
		${ove_cmd2pathname["rm"]:?} -rf ${OVE_OWEL_TMP_DIR}/unittest
	fi

	if ove_sanity_check_tmux 2> /dev/null; then
		ove-run-parallel 0 "ove shell-check" 0 "ove generate-doc" 0 "ove blame ${OVE_USER}"
		# run in separate session
		ove unittest
	else
		ove-shell-check
		ove-unittest
		ove-generate-doc
		ove-blame "${OVE_USER}"
	fi

	ove-status .ove
}

# refresh-image: :refresh list of available Linux distributions (incus|LXD only):UTIL
function ove-refresh-image {
	ove_entry || return

	local arch
	local c

	if ! c=$(ove_container_command); then
		return 1
	fi

	arch=$(${ove_cmd2pathname["uname"]:?} -m)
	if [ "${arch}" = "x86_64" ]; then
		arch="amd64"
	fi

	if ! ${ove_cmd2pathname["$c"]:?} image list --format csv -cL images: arch=${arch} | \
		${ove_cmd2pathname["sed"]:?} -e 's,",,g' -e '/^$/d' > "${OVE_GLOBAL_STATE_DIR:?}/distrocheck.images"; then
		ove_echo_error_noprefix "'$c image list images:' failed"
		return 1
	elif [ ! -s "${OVE_GLOBAL_STATE_DIR}/distrocheck.images" ]; then
		ove_echo_error_noprefix "weird - empty image list"
		return 1
	fi

	LC_ALL="C" ${ove_cmd2pathname["sort"]:?} \
		-u \
		-o "${OVE_GLOBAL_STATE_DIR:?}/distrocheck.images" \
		"${OVE_GLOBAL_STATE_DIR:?}/distrocheck.images"
}

# post-push: :run OVE unittests within a few Linux distributions specified by ${OVE_DIR}/tests/distrocheck.list (incus|LXD only):INTERNAL
function ove-post-push {
	ove_entry || return

	local d
	local distro_list

	if [ ! -s "${OVE_DIR}/tests/distrocheck.list" ]; then
		return 1
	elif ! ove-refresh-image; then
		return 1
	fi

	mapfile -t distro_list <"${OVE_DIR}/tests/distrocheck.list"
	for d in "${distro_list[@]}"; do
		OVE_DISTROCHECK_CONTAINER_PREFIX=ove-ut \
			${OVE_DIR}/distrocheck "unittest" "${d}"
	done
}

# post-push-parallel: :post-push in parallel (tmux and incus|LXD only):INTERNAL
function ove-post-push-parallel {
	ove_entry || return

	local args
	local d

	if [ ! -s "${OVE_DIR}/tests/distrocheck.list" ]; then
		return 1
	elif ! ove_sanity_check_tmux; then
		ove_command_usage
		return 1
	elif ! ove-refresh-image; then
		return 1
	fi

	while read -r d; do
		args+=" 0 'OVE_DISTROCHECK_CONTAINER_PREFIX=ove-ut ${OVE_DIR}/distrocheck unittest $d'"
	done <"${OVE_DIR}/tests/distrocheck.list"

	eval ove-run-parallel $args
}

# logo: :logo:CORE
function ove-logo {
	ove_entry || return

	if ! ove_check_command "convert"; then
		return 1
	elif ! ove_check_command "jp2a"; then
		return 1
	elif [ ! -s "${OVE_DIR:?}/ove.png" ]; then
		echo "error: '${OVE_DIR:?}/ove.png' not found" 1>&2
		return 1
	fi

	${ove_cmd2pathname["convert"]:?} "${OVE_DIR:?}/ove.png" jpg:- | \
		${ove_cmd2pathname["jp2a"]:?} --colors --fill -
}

# ps: :list current OVE processes:DEBUG
function ove-ps {
	ove_entry || return

	local c
	local cmdline
	local p

	if ! ove_check_command "pstree"; then
		return 1
	elif [ ! -d /proc ]; then
		ove_echo_error_noprefix "directory '/proc' is not available"
		return 1
	fi

	for p in $(${ove_cmd2pathname["pgrep"]:?} -f ${ove_cmd2pathname["script"]:?}); do
		mapfile -d '' -t cmdline < "/proc/${p}/cmdline"
		c=${cmdline[-1]}
		c=${c%%-"${HOSTNAME}"*}
		c=${c##*ove-}
		echo -n "$c:"
		${ove_cmd2pathname["pstree"]:?} -a -l -p $p
	done
}

ove_main "$@"