functions documentation

Author: MacDada

git_sync.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 ##
-# Synchronizes current branch with remote's master/main.
+# Synchronizes branch(es) with remote's master/main.
 #
 #   `./git_sync.sh`      – updates current branch with changes from remote/master
 #   `./git_sync.sh` all  – updates all branches with changes from remote/master
@@ -13,6 +13,15 @@ FORMAT_GREEN="\033[32m"
 FORMAT_YELLOW="\033[33m"
 FORMAT_RESET="\033[0m"
 
+##
+# @param string $1 Message to print
+#
+# @global FORMAT_ITALIC
+# @global FORMAT_GREEN
+# @global FORMAT_RESET
+#
+# @stdout Formatted message
+##
 print_info() {
   local message="${1}"
 
@@ -26,6 +35,15 @@ print_info() {
   printf "%b" "${FORMAT_RESET}"
 }
 
+##
+# @param string $1 Message to print
+#
+# @global FORMAT_ITALIC
+# @global FORMAT_YELLOW
+# @global FORMAT_RESET
+#
+# @stdout Formatted message
+##
 print_warning() {
   local message="${1}"
 
@@ -39,6 +57,15 @@ print_warning() {
   printf "%b" "${FORMAT_RESET}"
 }
 
+##
+# @param string $1 Message to print
+#
+# @global FORMAT_ITALIC
+# @global FORMAT_RED
+# @global FORMAT_RESET
+#
+# @stdout Formatted message
+##
 print_error() {
   local message="${1}"
 
@@ -52,6 +79,13 @@ print_error() {
   printf "%b" "${FORMAT_RESET}"
 }
 
+##
+# @param string... $@ The command and its arguments to execute
+#
+# @stdout The command and its output
+#
+# @return Exit code of the executed command
+##
 print_and_run() {
   # Print the command.
   print_info "\n➤ ${*}\n"
@@ -63,6 +97,13 @@ print_and_run() {
   "${@}"
 }
 
+##
+# @global default_branch
+#
+# @stdout Error message, when not able to detect the default branch
+#
+# @exit 1 On not able to detect the default branch
+#
 detect_default_branch() {
   if local_branch_exists "master"; then
     default_branch="master"
@@ -75,29 +116,51 @@ detect_default_branch() {
   fi
 }
 
+##
+# @stdout Number of stashes (integer)
+#
 count_stashes () {
   # `wc` generates a value with whitespace.
   # `xargs` trims the whitespace.
   git stash list | wc -l | xargs
 }
 
+##
+# @stdout Branch names, one per line
+##
 list_local_branches() {
   git for-each-ref --format='%(refname:short)' refs/heads/
 }
 
+##
+# @param string $1 Branch name
+#
+# @return 0 When branch exists
+# @return 1 When branch does not exist
+##
 local_branch_exists() {
   local branch="${1}"
 
   git show-ref --verify --quiet "refs/heads/${branch}"
 }
 
-# Returns 0 (true) if the branch exists on origin, 1 (false) otherwise
+##
+# @param string $1 Branch name
+#
+# @return 0 When branch exists
+# @return 1 When branch does not exist
+##
 remote_branch_exists() {
   local branch="${1}"
 
   git show-ref --verify --quiet "refs/remotes/origin/${branch}"
 }
 
+##
+# @stdout Combined sync_branch() output
+#
+# @global default_branch Used to skip syncing the default branch
+##
 sync_all_branches() {
   local branch
 
@@ -109,13 +172,22 @@ sync_all_branches() {
   done
 }
 
+##
+# @param string $1 Branch name
+#
+# @stdout Sync process and/or warnings/errors
+#
+# @return 0 Successful sync
+# @return 1 Sync skipped (remote branch exists)
+# @return 2 Sync rebase aborted (conflicts)
+##
 sync_branch() {
   local branch="${1}"
 
   if remote_branch_exists "${branch}"; then
     print_warning "\n⚠ Sync aborted on branch \"${branch}\" as it exists on origin."
 
-    return
+    return 1
   fi
 
   print_and_run git checkout "${branch}"
@@ -124,9 +196,16 @@ sync_branch() {
     print_and_run git rebase --abort
 
     print_error "⚠ Rebase aborted on branch \"${branch}\" due to conflicts!"
+
+    return 2
   fi
+
+  return 0
 }
 
+##
+# Main script execution
+##
 detect_default_branch
 print_info "\nDetected default branch: \"${default_branch}\"."