add-hook

The kilm add-hook command creates or modifies a Git post-merge hook script in a specified repository. This hook is designed to automatically run kilm sync after successful git pull or git merge operations, helping keep your KiLM-managed libraries synchronized.

Usage

kilm add-hook [OPTIONS]

Options

Option	Description	Default	Example
--directory DIRECTORY	Path to the Git repository directory	Current working directory	--directory ~/my-kicad-libs-repo
--force	Overwrite existing hook if present	False	--force
--help	Show help message and exit	-	--help

Behavior

The command performs the following actions:

1. Detects Active Hooks Directory:

   • Queries git config core.hooksPath for custom hooks directory
   • Falls back to .git/hooks (standard location)
   • Handles Git worktrees where hooks live in the linked location

2. Checks Existing Hook: Looks for an existing post-merge file

3. Creates Safe Backup: If a hook exists, creates a timestamped backup before modification

4. Intelligent Content Management:

   • If KiLM content already exists, updates the managed section
   • If other content exists, merges KiLM content with clear markers
   • Preserves existing user logic while adding KiLM functionality

5. Writes Hook Script: Creates or updates the hook file with executable content

6. Sets Permissions: Ensures the hook has executable permissions (chmod +x)

Examples

Basic Usage

Add hook to current Git repository:

# Navigate to your KiCad library repository
cd ~/kicad-libraries

# Add the hook
kilm add-hook

Add hook to specific repository:

kilm add-hook --directory /path/to/another/kicad-lib-repo

Advanced Usage

Force overwrite existing hook:

kilm add-hook --directory ~/my-libs --force

Hook Script Content

The command creates a post-merge hook with the following structure:

#!/bin/sh
# BEGIN KiLM-managed section
# KiCad Library Manager auto-update hook
# Added by kilm add-hook command

echo "Running KiCad Library Manager sync..."
kilm sync

# Uncomment to set up libraries automatically (use with caution)
# kilm setup

echo "KiCad libraries update complete."
# END KiLM-managed section

Advanced Features

Custom Hooks Directory

If your repository uses git config core.hooksPath to specify a custom hooks directory, KiLM will automatically detect and use that location.

# Example: Repository with custom hooks path
git config core.hooksPath ~/.git-hooks
kilm add-hook  # Will use ~/.git-hooks/post-merge

Git Worktree Support

For repositories using Git worktrees, KiLM correctly identifies the main repository location and installs hooks in the appropriate hooks directory.

Safe Updates

• First Run: Creates a new hook with KiLM content
• Subsequent Runs: Updates only the KiLM-managed section, preserving other customizations
• Backup Protection: Always creates timestamped backups before modifications
• Idempotent: Safe to run multiple times without duplicating content

Customization

You can manually edit the generated hook script to add more functionality. For example, to automatically run kilm setup after updating:

#!/bin/sh
# BEGIN KiLM-managed section
# KiCad Library Manager auto-update hook
# Added by kilm add-hook command

echo "Running KiCad Library Manager sync..."
kilm sync

# Uncomment to set up libraries automatically (use with caution)
kilm setup

echo "KiCad libraries update complete."
# END KiLM-managed section

Error Handling

Common Issues

• Not a Git repository: Command will fail if the directory is not a valid Git repository
• Permission denied: Command will fail if unable to write to the hooks directory
• Existing hook conflicts: Use --force to overwrite existing hooks

Error Examples

# Not a Git repository
kilm add-hook --directory /regular/directory
# Error: Not a git repository

# No write permissions
kilm add-hook --directory /readonly/repo
# Error: Permission denied when writing hook file

Integration with Other Commands

sync The command that gets executed by the post-merge hook

setup Can be optionally added to the hook for automatic setup

status Check hook installation status

Notes

• Git Integration: Hook only runs after successful git pull or git merge operations
• Cross-platform: Works on Windows, macOS, and Linux (uses appropriate shell syntax)
• Safety: Creates backups before modifying existing hooks
• Idempotent: Safe to run multiple times without side effects
• Customizable: Generated hook can be manually modified for additional functionality