Skip to content

Development Guide

Directory Structure

immich-auto-stack/
├── cmd/                # CLI entrypoint (main.go)
├── pkg/
│   ├── stacker/        # Stacking logic, types, and tests
│   ├── immich/         # Immich API client and integration
│   └── utils/          # Utility helpers and logging

Building Locally

# Build locally
docker build -t immich-stack .

# Run locally
docker run -d \
  --name immich-stack \
  --env-file .env \
  -v ./logs:/app/logs \
  immich-stack

Code Style

  • Follow the code style and comment conventions (see code for examples)
  • Add tests for new features
  • Document all exported functions and types

Extending

  • Custom Grouping: Edit or override criteria via command-line flags or environment variables
  • Custom Promotion: Set --parent-filename-promote and/or --parent-ext-promote for your workflow
  • API Integration: Extend pkg/immich/client.go for new Immich endpoints

Library Structure

pkg/stacker

  • StackBy: Groups assets into stacks and sorts them based on promotion rules
  • SortStack: Sorts assets in a stack by promotion and extension rules
  • Types: Asset, Stack, Criteria, etc.

pkg/immich

  • Client: Handles all Immich API interactions (fetch, modify, delete stacks/assets)
  • FetchAllStacks: Retrieves all stacks, with reset and cleanup logic
  • FetchAssets: Retrieves all assets, paginated
  • ModifyStack/DeleteStack: Stack management
  • ListDuplicates: Finds and logs duplicate assets

pkg/utils

  • helper.go: Array comparison, string cleaning
  • logs.go: Colorful, structured logging helpers (info, error, debug, pretty-print)