Tooling

• 1: Use plantuml pre-commit hook to automatically generate diagrams
• 2: Prek an alternative to pre-commit

1 - Use plantuml pre-commit hook to automatically generate diagrams

1. Overview

The PlantUML pre-commit hook from bash-tools-framework automatically generates image files (SVG and PNG) from PlantUML (.puml) files whenever they are committed. This ensures diagrams stay synchronized with their source files and eliminates manual export steps.

2. Configuration

2.1. Basic Setup

Add the PlantUML hook to your .pre-commit-config.yaml file:

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master  # or a specific tag/commit (e.g., v6.2.10)
    hooks:
      - id: plantuml

This configuration will:

• Generate both PNG and SVG files by default
• Place generated images in the same directory as the source .puml file
• Only process changed .puml files (not all files on every commit)
• Run during the pre-commit stage

2.2. Hook Configuration Details

The PlantUML hook has the following characteristics:

2.3. Customizing Arguments

You can customize the hook behavior by overriding the default arguments:

2.3.1. Output Format Options

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master
    hooks:
      - id: plantuml
        args: [--ci, --same-dir, -f, svg]  # Only generate SVG

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master
    hooks:
      - id: plantuml
        args: [--ci, --same-dir, -f, png]  # Only generate PNG

2.3.2. Output Directory Options

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master
    hooks:
      - id: plantuml
        args: [--ci, -f, svg, -o, diagrams/]  # Output to specific directory

2.4. Available Arguments

3. Usage Workflow

3.1. Automatic Generation on Commit

1. Edit your .puml file:

   vim content/docs/architecture/system-diagram.puml
   

2. Stage the file:

   git add content/docs/architecture/system-diagram.puml
   

3. Commit - the hook runs automatically:

   git commit -m "docs: update system diagram"
   

   The hook will:

   • Detect the changed .puml file
   • Generate system-diagram.svg and system-diagram.png
   • if a new file is generated or an existing file is updated, it will automatically stop the commit
   • Stage the modified files
   • Complete the commit with all files included

3.2. Manual Generation

Run the hook manually without committing:

pre-commit run plantuml --all-files                  # Process all .puml files
pre-commit run plantuml --files path/to/diagram.puml # Process specific file

3.3. Skipping the Hook

If you need to commit .puml files without regenerating images:

git commit --no-verify -m "WIP: diagram in progress"

4. Integration with PlantUML Best Practices

This hook works seamlessly with modular PlantUML architecture:

• Reusable components - hooks process included files correctly
• Theme files - changes to shared themes trigger regeneration
• Master diagrams - composite diagrams update when subsections change

For comprehensive examples of creating modular, reusable PlantUML diagrams, see:

• Reusable PlantUML Components guide

5. Advanced Configuration

5.1. Skip Specific Files

Use the exclude pattern to skip certain .puml files:

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master
    hooks:
      - id: plantuml
        # Skip files in scratch/ and drafts/
        exclude: ^scratch/|^drafts/

5.2. Multiple Output Configurations

If you need different formats for different directories:

repos:
  - repo: https://github.com/fchastanet/bash-tools-framework
    rev: master
    hooks:
      - id: plantuml
        name: plantuml-docs
        files: ^content/docs/.*\.puml$
        args: [--ci, --same-dir, -f, svg]  # Docs use SVG only

      - id: plantuml
        name: plantuml-presentations
        files: ^presentations/.*\.puml$
        args: [--ci, --same-dir, -f, png]  # Presentations use PNG

6. Benefits

• Automation: No manual export steps required
• Consistency: All diagrams generated with same settings
• Version Control: Generated images automatically tracked with sources
• Developer Experience: Edit .puml files in any editor, images update on commit
• CI/CD Ready: Works in automated pipelines with --ci flag

7. See Also

• Reusable PlantUML Components - Learn to create modular diagrams
• bash-tools-framework .pre-commit-hooks.yaml - Full hook reference

2 - Prek an alternative to pre-commit

Prek is a modern alternative to pre-commit, designed to be faster and easier to use. It provides a streamlined experience for managing and running pre-commit hooks, with a focus on performance and simplicity.

From the author:

pre-commit is a framework to run hooks written in many languages, and it manages the language toolchain and dependencies for running the hooks. prek is a reimagined version of pre-commit, built in Rust. It is designed to be a faster, dependency-free and drop-in alternative for it, while also providing some additional long-requested features.

1. Key Features of Prek

• Speed: Prek is optimized for speed, allowing you to run hooks quickly and efficiently.
• Ease of Use: With a simple configuration and intuitive commands, Prek makes it easy to set up and manage your pre-commit hooks.
• Compatibility: Prek is compatible with existing pre-commit configurations, making it easy to switch without losing your current setup.
• Extensibility: Prek supports custom hooks and integrations, allowing you to tailor it to your specific needs.

2. Getting Started with Prek

2.1. Install Prek

# Install Prek
pip install prek

2.2. Initialize Prek in Your Repository

# Initialize Prek in your repository
prek sample-config -f .pre-commit-config.yaml --format yaml
# Run Prek to execute pre-commit and pre-push hooks
prek install --install-hooks -t pre-push -t pre-commit --overwrite

2.3. Initialize Prek on a repository that was using pre-commit

# Install prek hooks, it will overwrite your existing pre-commit configuration with a Prek configuration
prek install --install-hooks
# by default prek will keep existing pre-commit hooks, to remove them you can use the --overwrite flag
prek install --install-hooks -t pre-push -t pre-commit --overwrite

2.4. Run Prek

# Run Prek to execute pre-commit and pre-push hooks on all files (staged or not)
prek run -a

3. Performance benchmarks

Happier Developers, Faster Teams: Why Prek Beats Pre-commit Backup page of the above article

4. Conclusion

Prek is a powerful and efficient alternative to pre-commit, offering improved performance and a more user-friendly experience. Whether you’re looking to speed up your pre-commit hooks or simplify your workflow, Prek is a great choice for modern development teams. Give it a try and see the difference it can make in your development process!

Prek GitHub Repository