feat(git): add comprehensive git folder management commands and update documentation

bin/add-git-folder

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+add-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/branch is empty.'
+        exit
+    fi
+    if [[ -z "$2" ]]; then
+        echo '$2/url is empty.'
+        exit
+    fi
+    if [[ -z "$3" ]]; then
+        echo '$3/path is empty.'
+        exit
+    fi
+
+    # Add to .gitmodules
+    git submodule add -f -b "$1" "$2" "$3"
+
+    # Ensure branch is Odoo version
+    git -C "$3" switch "$1"
+
+    # Save version
+    save-version
+
+    # Restore staged submodule files
+    git restore --staged .gitmodules "$3"
+
+    # Remove from working tree
+    # rm -rf .git/modules/"$2" || true
+    # git rm --cached "$2" || true
+}

bin/aggregate-git-folders

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+aggregate-git-folders() {
+    if [[ -z "$1" ]]; then
+        echo '$1 is empty.'
+        exit
+    fi
+
+    gitaggregate -c "$1" --expand-env
+}

bin/checkout-git-folder

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+checkout-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+    if [[ -z "$2" ]]; then
+        echo '$2/path is empty.'
+        exit
+    fi
+
+    local git_branch="$1"
+    local git_folders=$(ls-git-folder "$2")
+    for git_folder in $git_folders; do
+
+        git_folder="${git_folder#./}"
+
+        local shallow=$(git config --file .gitmodules --get submodule."$git_folder".shallow)
+        local commit_ref=$(grep "$git_folder" ".gitmodules.csv" | cut -d',' -f2)
+
+        if [[ "$shallow" = "true" ]]; then
+            echo "Checkout git folder $git_folder (shallow) to $commit_ref"
+            git -C "$git_folder" stash
+            git -C "$git_folder" fetch origin "$git_branch:$git_branch"
+            git -C "$git_folder" checkout "$commit_ref"
+        else
+            echo "Checkout git folder $git_folder to $commit_ref"
+            git -C "$git_folder" stash
+            git -C "$git_folder" checkout "$commit_ref"
+        fi
+    done
+}

bin/clean-git-folder

@@ -1,7 +1,12 @@
 #!/usr/bin/env bash
 
 clean-git-folder() {
-    local git_folders=$(ls-git-folder)
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+
+    local git_folders=$(ls-git-folder "$1")
     for git_folder in $git_folders; do
         echo "Clean git folder $git_folder."
         git -C "$git_folder" clean -df

bin/clone-git-folder

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+clone-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+
+    local git_folders=$(ls-git-folder "$1")
+    for git_folder in $git_folders; do
+
+        git_folder="${git_folder#./}"
+
+        local git_folder_path=$(git config --file .gitmodules --get submodule."$git_folder".path)
+        local git_folder_url=$(git config --file .gitmodules --get submodule."$git_folder".url)
+        local shallow=$(git config --file .gitmodules --get submodule."$git_folder".shallow)
+        local git_folder_branch=$(git config --file .gitmodules --get submodule."$git_folder".branch)
+
+        if [[ "$shallow" = "true" ]]; then
+            echo "Clone git folder $git_folder (shallow) with $git_folder_branch branch"
+            git -C "$git_folder" config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
+            git clone --depth 1 --no-single-branch "$git_folder_url" "$git_folder_path"
+        else
+            echo "Clone git folder $git_folder with $git_folder_branch branch"
+            git clone --branch="$git_folder_branch" "$git_folder_url" "$git_folder_path"
+        fi
+    done
+}

bin/download-git-folder

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+download-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+
+    local git_folders=$(ls-git-folder "$1")
+    for git_folder in $git_folders; do
+
+        local git_folder_path=$(git config --file .gitmodules --get submodule."$git_folder".path)
+        local git_folder_url=$(git config --file .gitmodules --get submodule."$git_folder".url)
+        local git_folder_branch=$(git config --file .gitmodules --get submodule."$git_folder".branch)
+
+        # Convert git url to http url.
+        git_folder_url="$(echo $git_folder_url | sed 's|git@|https://|g' | sed 's|m:|m/|g' | sed 's|\.git||g')"
+
+        # Get commit ref from .gitmodule.csv
+        local commit_ref=$(grep "$git_folder_path" ".gitmodules.csv" | cut -d',' -f2)
+
+        echo "Download $git_folder_url to $git_folder_path."
+        mkdir -p "$git_folder_path"
+        curl -L -o "$git_folder_path/archive.tar.gz" \
+            "$git_folder_url/archive/$commit_ref.tar.gz"
+
+        echo "Extract and delete $git_folder_path/archive.tar.gz"
+        tar -xzf "$git_folder_path/archive.tar.gz" --strip-components=1 -C "$git_folder_path"
+        rm "$git_folder_path/archive.tar.gz"
+    done
+}

bin/list-git-folder

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+list-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+    
+    # Define column widths
+    local path_width=35
+    local url_width=50
+    local branch_width=8
+
+    # Print table header
+    printf "| %-${path_width}s | %-${url_width}s | %-${branch_width}s |\n" "PATH" "URL" "BRANCH"
+    echo "|$(printf '%*s' $((path_width + 2)) '' | tr ' ' '-')|$(printf '%*s' $((url_width + 2)) '' | tr ' ' '-')|$(printf '%*s' $((branch_width + 2)) '' | tr ' ' '-')|"
+
+    local git_folders=$(ls-git-folder "$1")
+    for git_folder in $git_folders; do
+        local url=$(git config --file .gitmodules --get "submodule.$git_folder.url")
+        url=${url#git@github.com:}
+        url=${url%.git}
+        local branch=$(git -C "$git_folder" branch --show-current 2>/dev/null || echo "detached")
+        printf "| %-${path_width}s | %-${url_width}s | %-${branch_width}s |\n" "$git_folder" "$url" "${branch:-detached}"
+    done
+}

bin/ls-git-folder

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 
-#!/usr/bin/env bash
-
 ls-git-folder() {
-    [[ -z "$1" ]] && { echo '$1 is empty.' >&2; return 1; }
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
     [[ ! -d "$1" ]] && { echo "Error: '$1' is not a directory." >&2; return 1; }
 
     local excludes="${GIT_FOLDER_EXCLUDE:-.cache,node_modules,venv,__pycache__,.vim,.fzf,.password-store,.oh-my-zsh}"
@@ -18,6 +19,6 @@ ls-git-folder() {
     find_cmd="$find_cmd -type d -name '.git' -print"
 
     eval "$find_cmd" 2>/dev/null | while IFS= read -r git_dir; do
-        dirname "$git_dir"
+        [[ "$git_dir" != "./.git" ]] && dirname "$git_dir"
     done
 }

bin/pull-git-folder

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+pull-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/branch is empty.'
+        exit
+    fi
+    if [[ -z "$2" ]]; then
+        echo '$2/path is empty.'
+        exit
+    fi
+
+    local git_folders=$(ls-git-folder "$2")
+    for git_folder in $git_folders; do
+        echo "Pull git folder $git_folder."
+        git -C "$git_folder" stash
+        local update=$(git config submodule."$git_folder".update)
+        if [[ -z "$update" ]]; then
+            git -C "$git_folder" pull origin "$1"
+        fi;
+    done
+}

bin/remove-git-folder

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+remove-git-folder() {
+    if [[ -z "$1" ]]; then echo "\$1 is empty."; exit; fi
+    local git_folders=$(ls-git-folder "$1")
+
+    echo "Delete: $git_folders"
+    read -p "Are you sure to delete these git folder(s)? (yes/N): " confirm
+    if [[ "${confirm,,}" != "yes" ]]; then
+        echo 'Aborted.'
+        return 1
+    fi
+    for git_folder in $git_folders; do
+        echo "Remove $git_folder from .gitmodules file."
+        git config --file .gitmodules --remove-section "submodule.$git_folder"
+
+        echo "Delete git folder $git_folder."
+        rm -rf "$git_folder"
+    done
+
+    save-version
+}

bin/reset-git-folder

@@ -1,7 +1,12 @@
 #!/usr/bin/env bash
 
 reset-git-folder() {
-    local git_folders=$(ls-git-folder)
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+
+    local git_folders=$(ls-git-folder "$1")
     for git_folder in $git_folders; do
         echo "Abort rebase and reset git folder $git_folder."
         git -C "$git_folder" rebase --abort

bin/switch-git-folder

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+switch-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/path is empty.'
+        exit
+    fi
+    if [[ -z "$2" ]]; then
+        echo '$2/path is empty.'
+        exit
+    fi
+
+    local git_branch="$1"
+    local git_folders=$(ls-git-folder "$2")
+    for git_folder in $git_folders; do
+
+        git_folder="${git_folder#./}"
+
+        local shallow=$(git config --file .gitmodules --get submodule."$git_folder".shallow)
+
+        if [[ "$shallow" = "true" ]]; then
+            echo "Fetch branch $git_branch (shallow) from origin and then switch."
+            git -C "$git_folder" fetch origin "$git_branch:$git_branch"
+            git -C "$git_folder" switch "$git_branch"
+        else
+            echo "Switch git folder branch to $git_branch: $git_folder"
+            git -C "$git_folder" stash
+            git -C "$git_folder" switch "$git_branch"
+        fi
+    done
+}

bin/sync-git-folder

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+sync-git-folder() {
+    if [[ -z "$1" ]]; then
+        echo '$1/branch is empty.'
+        exit
+    fi
+    if [[ -z "$2" ]]; then
+        echo '$2/path is empty.'
+        exit
+    fi
+
+    echo 'Switch and pull git folders.'
+    switch-git-folder "$"
+    pull-git-folder "$1" "$1"
+}