From 1dd941652bbb333cdf617d0a994a3352011df835 Mon Sep 17 00:00:00 2001 From: Rodrigo Pastrana Date: Fri, 7 Nov 2025 14:45:23 -0500 Subject: [PATCH] Add auto submodule update hook - Adds post-checkout hook - Adds optional script to copy onto hpcc-platform clone - Adds README Signed-off-by: Rodrigo Pastrana --- rjp/git/autosubmoduleupdate/README.md | 266 ++++++++++++++++++ .../install-to-hpcc-platform.sh | 147 ++++++++++ rjp/git/autosubmoduleupdate/post-checkout | 25 ++ 3 files changed, 438 insertions(+) create mode 100644 rjp/git/autosubmoduleupdate/README.md create mode 100755 rjp/git/autosubmoduleupdate/install-to-hpcc-platform.sh create mode 100755 rjp/git/autosubmoduleupdate/post-checkout diff --git a/rjp/git/autosubmoduleupdate/README.md b/rjp/git/autosubmoduleupdate/README.md new file mode 100644 index 0000000..a057c26 --- /dev/null +++ b/rjp/git/autosubmoduleupdate/README.md @@ -0,0 +1,266 @@ +# Git Submodule Auto-Update Tool + +Automatically update git submodules when switching branches to maintain consistent submodule state across your development workflow and prevent build corruption. + +## 🎯 **Problem Solved** + +When working with git repositories that contain submodules (like HPCC Platform with `esp/src/dgrid` and `vcpkg`), manually running `git submodule update --init --recursive` after every branch switch becomes tedious and error-prone. + +**⚠️ Critical for HPCC Platform**: Failing to update the `vcpkg` submodule when switching branches can lead to **serious build corruption**. Building with an outdated vcpkg hash can corrupt the vcpkg install/build process, requiring time-consuming cleanup and rebuilds. This tool prevents these costly issues by ensuring submodules are always synchronized with the current branch. + +## 🚀 **Features** + +- **Prevents vcpkg build corruption** by ensuring consistent package manager state +- **Automatic submodule updates** when checking out branches +- **Enhanced git submodule visibility** in status and diff commands +- **Team-wide consistency** through shared configuration +- **Smart detection** - only runs on branch checkouts, not file checkouts +- **Clear feedback** - shows when submodules are being updated + +## 📋 **What's Included** + +- `post-checkout` - Git hook that automatically runs submodule updates +- `install-hooks.sh` - Setup script for easy installation +- `README.md` - This documentation + +## 🔧 **Installation** + +### Quick Setup (Recommended) + +```bash +# 1. Copy files to your repository's githooks directory +cp post-checkout /path/to/your/repo/githooks/ +cp install-hooks.sh /path/to/your/repo/ + +# 2. Run the installation script +cd /path/to/your/repo +./install-hooks.sh +``` + +### Manual Setup + +```bash +# 1. Copy the post-checkout hook +cp post-checkout /path/to/your/repo/.git/hooks/ +chmod +x /path/to/your/repo/.git/hooks/post-checkout + +# 2. Configure git for better submodule handling +git config submodule.recurse true +git config status.submoduleSummary true +git config diff.submodule log +``` + +## 💡 **Usage** + +Once installed, the tool works transparently: + +```bash +# Normal git workflow - submodules update automatically +git checkout feature-branch +# Output: Branch checkout detected. Updating submodules... +# Output: Submodules updated successfully. + +git checkout main +# Output: Branch checkout detected. Updating submodules... +# Output: Submodules updated successfully. +``` + +## 🔍 **Enhanced Git Commands** + +After installation, you'll also get enhanced git output: + +```bash +# git status shows submodule summaries +git status +# Shows: * submodule-name abc1234...def5678 (2): +# > Recent submodule commit message + +# git diff shows submodule changes as commit ranges +git diff +# Shows: Submodule submodule-name abc1234..def5678: +# < Old commit message +# > New commit message +``` + +## ��️ **How It Works** + +The `post-checkout` hook: +1. **Detects branch checkouts** (vs. file checkouts) using git hook parameters +2. **Runs `git submodule update --init --recursive`** to sync submodules +3. **Provides feedback** about the update process +4. **Exits with error codes** if submodule updates fail + +## 📁 **File Descriptions** + +### `post-checkout` +Git hook that automatically updates submodules when switching branches. +- **Trigger**: After successful `git checkout` of a branch +- **Action**: Runs `git submodule update --init --recursive` +- **Safety**: Only runs on branch checkouts, not file checkouts + +### `install-hooks.sh` +Convenience script for team-wide deployment. +- Copies all hooks from `githooks/` to `.git/hooks/` +- Makes hooks executable +- Configures git for enhanced submodule handling +- Provides setup confirmation + +## 🎛️ **Configuration Options** + +The installation script sets these git configurations: + +| Setting | Effect | +|---------|--------| +| `submodule.recurse true` | Git commands automatically recurse into submodules | +| `status.submoduleSummary true` | `git status` shows submodule change summaries | +| `diff.submodule log` | `git diff` shows submodule changes as commit ranges | + +## ⚠️ **Important Notes** + +- **vcpkg corruption prevention**: Essential for HPCC Platform builds to avoid package manager state corruption +- **Team deployment**: Each developer needs to run the installation script +- **Repository-specific**: Configuration is per-repository, not global +- **Backup existing hooks**: If you have existing git hooks, back them up first +- **Submodule conflicts**: If submodule updates fail, the hook will exit with an error + +## 🔄 **Compatibility** + +- **Git versions**: Compatible with Git 2.7+ (supports `submodule.recurse`) +- **Operating systems**: Linux, macOS, Windows (with Git Bash) +- **Repository types**: Any git repository with submodules + +## 🐛 **Troubleshooting** + +### Hook not executing +```bash +# Check if hook is executable +ls -la .git/hooks/post-checkout +# Should show: -rwxr-xr-x + +# Make executable if needed +chmod +x .git/hooks/post-checkout +``` + +### Submodule update failures +```bash +# Check submodule status +git submodule status + +# Manual update to diagnose issues +git submodule update --init --recursive +``` + +### vcpkg corruption recovery +```bash +# If vcpkg gets corrupted, clean and rebuild +rm -rf build/vcpkg_installed/ build/vcpkg_packages/ +git submodule update --init --recursive +# Then rebuild your project +``` + +### Disable temporarily +```bash +# Rename hook to disable +mv .git/hooks/post-checkout .git/hooks/post-checkout.disabled + +# Rename back to enable +mv .git/hooks/post-checkout.disabled .git/hooks/post-checkout +``` + +## 📚 **Examples** + +### HPCC Platform Repository +This tool was originally developed for the HPCC Platform repository which has critical submodules: +- `esp/src/dgrid` - UI grid component +- `vcpkg` - C++ package manager (critical for build integrity) + +### Typical Workflow with Build Safety +```bash +# Developer workflow with automatic submodule updates +git checkout main +# vcpkg submodule automatically updated to main's version - build safe! + +git checkout HPCC-12345-new-feature +# vcpkg submodule automatically updated to feature branch's version - no corruption! + +# Build with confidence - vcpkg is synchronized +cmake --build build --parallel + +git status +# Shows any submodule changes clearly + +git diff +# Shows submodule changes as readable commit ranges +``` + +### Without This Tool (Problematic) +```bash +# Dangerous workflow without automatic updates +git checkout HPCC-12345-new-feature +# vcpkg submodule still points to old commit +cmake --build build --parallel +# 💥 Build corruption due to vcpkg version mismatch! +``` + +## 🤝 **Contributing** + +To improve this tool: +1. Test with your repository setup +2. Submit issues for any problems encountered +3. Propose enhancements via pull requests + +## 📄 **License** + +This tool is part of the HPCC Systems DeveloperTools collection and follows the same license terms. + +--- + +**Author**: RJP +**Created**: November 2025 +**Purpose**: Streamline git submodule management and prevent vcpkg build corruption in HPCC Platform development + +## 🏗️ **For HPCC-Platform Developers** + +### One-Command Installation from DeveloperTools + +If you have a local clone of the DeveloperTools repository, you can install this tool to your HPCC-Platform repository with a single command: + +```bash +# From your DeveloperTools clone +cd DeveloperTools/rjp/git/autosubmoduleupdate +./install-to-hpcc-platform.sh +``` + +The installer will: +- 🔍 **Auto-detect** your HPCC-Platform repository in common locations: + - `$HOME/GIT/HPCC-Platform` + - `$HOME/git/HPCC-Platform` + - Same parent directory as DeveloperTools + - And several other common paths +- ✅ **Verify** it's actually an HPCC-Platform repository +- 💾 **Backup** any existing git hooks +- 📦 **Install** the post-checkout hook and configuration +- 🎯 **Configure** git for enhanced submodule handling + +### Manual Path Specification + +If your HPCC-Platform is in a custom location: + +```bash +cd DeveloperTools/rjp/git/autosubmoduleupdate +./install-to-hpcc-platform.sh /path/to/your/HPCC-Platform +``` + +### Verification + +After installation, test that it works: + +```bash +cd /path/to/your/HPCC-Platform +git checkout main +# Output: Branch checkout detected. Updating submodules... +# Output: Submodules updated successfully. +``` + +Now you're protected from vcpkg build corruption! 🛡️ + diff --git a/rjp/git/autosubmoduleupdate/install-to-hpcc-platform.sh b/rjp/git/autosubmoduleupdate/install-to-hpcc-platform.sh new file mode 100755 index 0000000..f07526a --- /dev/null +++ b/rjp/git/autosubmoduleupdate/install-to-hpcc-platform.sh @@ -0,0 +1,147 @@ +#!/bin/bash +# +# Install Git Submodule Auto-Update Tool to HPCC-Platform Repository +# +# This script installs the git hooks from DeveloperTools to your local +# HPCC-Platform repository to prevent vcpkg build corruption. +# +# Usage: +# ./install-to-hpcc-platform.sh [path-to-hpcc-platform] +# +# If no path is provided, it will look for HPCC-Platform in common locations. +# + +set -e # Exit on any error + +echo "🚀 HPCC-Platform Git Submodule Auto-Update Installer" +echo " Prevents vcpkg build corruption by auto-updating submodules" +echo "================================================================" +echo + +# Function to check if a directory is an HPCC-Platform repository +is_hpcc_platform() { + local dir="$1" + if [ -d "$dir/.git" ] && [ -f "$dir/CMakeLists.txt" ] && [ -d "$dir/esp" ] && [ -d "$dir/vcpkg" ]; then + return 0 + fi + return 1 +} + +# Function to find HPCC-Platform repository +find_hpcc_platform() { + local search_paths=( + "../../../HPCC-Platform" # Same parent as DeveloperTools + "../../HPCC-Platform" # One level up + "../HPCC-Platform" # Sibling directory + "$HOME/GIT/HPCC-Platform" # Common git directory + "$HOME/git/HPCC-Platform" # Lowercase variant + "$HOME/repos/HPCC-Platform" # Alternative structure + "$HOME/workspace/HPCC-Platform" # IDE workspace + "./HPCC-Platform" # Current directory + ) + + for path in "${search_paths[@]}"; do + if is_hpcc_platform "$path"; then + echo "$(cd "$path" && pwd)" + return 0 + fi + done + return 1 +} + +# Get the script directory (where the hook files are located) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +echo "📁 DeveloperTools location: $SCRIPT_DIR" + +# Check if required files exist +if [ ! -f "$SCRIPT_DIR/post-checkout" ]; then + echo "❌ Error: post-checkout hook not found in $SCRIPT_DIR" + echo " Make sure you're running this from the DeveloperTools/rjp/git/autosubmoduleupdate directory" + exit 1 +fi + +# Determine HPCC-Platform path +HPCC_PATH="" +if [ $# -eq 1 ]; then + # User provided path + HPCC_PATH="$1" + if [ ! -d "$HPCC_PATH" ]; then + echo "❌ Error: Directory '$HPCC_PATH' does not exist" + exit 1 + fi + HPCC_PATH="$(cd "$HPCC_PATH" && pwd)" # Convert to absolute path +else + # Auto-detect HPCC-Platform + echo "🔍 Searching for HPCC-Platform repository..." + HPCC_PATH=$(find_hpcc_platform) + if [ $? -ne 0 ]; then + echo "❌ Error: Could not find HPCC-Platform repository" + echo "" + echo "Please provide the path to your HPCC-Platform repository:" + echo " $0 /path/to/HPCC-Platform" + echo "" + echo "Or ensure HPCC-Platform is in one of these locations:" + echo " - Same parent directory as DeveloperTools" + echo " - \$HOME/GIT/HPCC-Platform" + echo " - \$HOME/git/HPCC-Platform" + exit 1 + fi +fi + +# Verify it's actually HPCC-Platform +if ! is_hpcc_platform "$HPCC_PATH"; then + echo "❌ Error: '$HPCC_PATH' does not appear to be an HPCC-Platform repository" + echo " Expected: .git directory, CMakeLists.txt, esp/, and vcpkg/ subdirectories" + exit 1 +fi + +echo "✅ Found HPCC-Platform: $HPCC_PATH" +echo + +# Check if there are existing git hooks and warn user +if [ -f "$HPCC_PATH/.git/hooks/post-checkout" ]; then + echo "⚠️ Warning: Existing post-checkout hook found" + echo " Current hook will be backed up as post-checkout.backup" + cp "$HPCC_PATH/.git/hooks/post-checkout" "$HPCC_PATH/.git/hooks/post-checkout.backup" + echo " ✓ Backup created: $HPCC_PATH/.git/hooks/post-checkout.backup" +fi + +# Create githooks directory in HPCC-Platform if it doesn't exist +echo "📁 Setting up githooks directory..." +mkdir -p "$HPCC_PATH/githooks" + +# Copy the post-checkout hook to githooks (for version control) +echo "📋 Installing post-checkout hook..." +cp "$SCRIPT_DIR/post-checkout" "$HPCC_PATH/githooks/" +cp "$SCRIPT_DIR/post-checkout" "$HPCC_PATH/.git/hooks/" + +# Make sure the hook is executable +chmod +x "$HPCC_PATH/.git/hooks/post-checkout" +chmod +x "$HPCC_PATH/githooks/post-checkout" + +# Configure git for better submodule handling +echo "⚙️ Configuring git settings for submodule management..." +cd "$HPCC_PATH" +git config submodule.recurse true +git config status.submoduleSummary true +git config diff.submodule log + +echo +echo "🎉 Installation successful!" +echo "================================================================" +echo "✅ Git Submodule Auto-Update Tool installed to HPCC-Platform" +echo "✅ vcpkg build corruption prevention is now active" +echo "✅ Enhanced submodule status and diff display enabled" +echo +echo "🔧 What was installed:" +echo " • $HPCC_PATH/.git/hooks/post-checkout" +echo " • $HPCC_PATH/githooks/post-checkout (for version control)" +echo " • Git configuration for submodule.recurse, status, and diff" +echo +echo "💡 Test the installation:" +echo " cd '$HPCC_PATH'" +echo " git checkout " +echo " # Should see: 'Branch checkout detected. Updating submodules...'" +echo +echo "🛡️ Protection active: vcpkg will automatically stay synchronized" +echo " No more build corruption from outdated package manager state!" diff --git a/rjp/git/autosubmoduleupdate/post-checkout b/rjp/git/autosubmoduleupdate/post-checkout new file mode 100755 index 0000000..e2a5bff --- /dev/null +++ b/rjp/git/autosubmoduleupdate/post-checkout @@ -0,0 +1,25 @@ +#!/bin/sh +# +# Post-checkout hook to automatically update submodules +# This hook is called after a successful 'git checkout' + +# Get the parameters passed by git +previous_head=$1 +new_head=$2 +branch_checkout=$3 + +# Only run for branch checkouts (not file checkouts) +# branch_checkout flag: 1 for branch checkout, 0 for file checkout +if [ "$branch_checkout" = "1" ]; then + echo "Branch checkout detected. Updating submodules..." + + # Update submodules to match the new branch + git submodule update --init --recursive + + if [ $? -eq 0 ]; then + echo "Submodules updated successfully." + else + echo "Warning: Submodule update failed." + exit 1 + fi +fi \ No newline at end of file