Skip to content

stack.md

Latest commit

 

History

History
216 lines (168 loc) · 6.78 KB

stack.md

File metadata and controls

216 lines (168 loc) · 6.78 KB

Stack Command

The stack command organizes related photos into stacks on your Immich server without uploading new content.

Syntax

immich-go stack [options]

Purpose

Stacking groups related photos together for better organization:

  • Burst photos from rapid shooting
  • RAW + JPEG pairs from cameras that shoot both formats
  • HEIC + JPEG pairs from iPhone/iPad Live Photos
  • Epson FastFoto scan groups (original, corrected, back side)

Required Options

Option Required Description
-s, --server Y Immich server URL
-k, --api-key Y Your API key

Connection Options

Option Default Description
--skip-verify-ssl false Skip SSL certificate verification
--client-timeout 20m Server call timeout
--api-trace false Enable API call tracing

Behavior Options

Option Default Description
--dry-run false Simulate stacking without making changes
--time-zone System Override timezone for date operations

Stacking Rules

Burst Photos

Option Values Description
--manage-burst NoStack, Stack, StackKeepRaw, StackKeepJPEG How to handle burst sequences

Detection Methods:

  • Time-based: Photos taken within 900ms of each other
  • Filename patterns: Device-specific naming conventions

Supported Devices:

  • Huawei: IMG_20231014_183246_BURST001_COVER.jpg, IMG_20231014_183246_BURST002.jpg
  • Google Pixel: PXL_20230330_184138390.MOTION-01.COVER.jpg, PXL_20230330_184138390.MOTION-02.ORIGINAL.jpg
  • Samsung: 20231207_101605_001.jpg, 20231207_101605_002.jpg
  • Sony Xperia: DSC_0001_BURST20230709220904977.JPG, DSC_0035_BURST20230709220904977_COVER.JPG
  • Nexus: 00001IMG_00001_BURST20171111030039.jpg, 00015IMG_00015_BURST20171111030039_COVER.jpg
  • Nothing: 00001IMG_00001_BURST1723801037429_COVER.jpg, 00002IMG_00002_BURST1723801037429.jpg

RAW + JPEG Management

Option Values Description
--manage-raw-jpeg NoStack, KeepRaw, KeepJPG, StackCoverRaw, StackCoverJPG Handle RAW+JPEG pairs
  • NoStack: Leave files separate
  • KeepRaw: Delete JPEG, keep RAW only
  • KeepJPG: Delete RAW, keep JPEG only
  • StackCoverRaw: Stack with RAW as cover image
  • StackCoverJPG: Stack with JPEG as cover image

HEIC + JPEG Management

Option Values Description
--manage-heic-jpeg NoStack, KeepHeic, KeepJPG, StackCoverHeic, StackCoverJPG Handle HEIC+JPEG pairs

Same logic as RAW+JPEG but for HEIC format files.

Epson FastFoto

Option Default Description
--manage-epson-fastfoto false Stack Epson FastFoto scan groups

File Pattern:

  • image-name.jpg (Original scan)
  • image-name_a.jpg (Corrected scan)
  • image-name_b.jpg (Back of photo)

When enabled, stacks all three with corrected scan as cover.

Examples

Basic Stacking

# Stack burst photos automatically
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-burst=Stack

# Preview stacking without changes
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-burst=Stack \
  --dry-run

RAW + JPEG Management

# Stack with RAW as cover
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-raw-jpeg=StackCoverRaw

# Keep only JPEG files
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-raw-jpeg=KeepJPG

Comprehensive Organization

# Handle all photo types
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-burst=Stack \
  --manage-raw-jpeg=StackCoverRaw \
  --manage-heic-jpeg=StackCoverJPG \
  --manage-epson-fastfoto=true

Safe Testing

# Test stacking rules without changes
immich-go stack \
  --server=http://localhost:2283 \
  --api-key=your-key \
  --manage-burst=Stack \
  --manage-raw-jpeg=StackCoverRaw \
  --dry-run

Detection Logic

Burst Detection Priority

  1. Filename patterns (device-specific)
  2. Time-based detection (900ms threshold)

File Pairing Logic

  1. Exact name matching (different extensions)
  2. Same directory location
  3. Similar timestamps (within reasonable range)

Best Practices

1. Test First

Always use --dry-run to preview changes:

immich-go stack --dry-run --manage-burst=Stack --server=... --api-key=...

2. Incremental Approach

Handle one type at a time:

# First, handle bursts
immich-go stack --manage-burst=Stack --server=... --api-key=...

# Then, handle RAW+JPEG
immich-go stack --manage-raw-jpeg=StackCoverRaw --server=... --api-key=...

3. Backup Consideration

Consider using the archive command before major organization:

immich-go archive from-immich --write-to-folder=/backup --server=... --api-key=...

4. Monitor Progress

Use logging to track operations:

immich-go stack \
  --log-level=DEBUG \
  --log-file=/tmp/stacking.log \
  --manage-burst=Stack \
  --server=... --api-key=...

Troubleshooting

Nothing Gets Stacked

  • Check photo timestamps and filenames
  • Verify photos are from supported devices
  • Use --api-trace to see server communication
  • Try --dry-run with --log-level=DEBUG

Unexpected Stacking

  • Review detection logic for your device type
  • Check if time-based detection is too aggressive
  • Use filename patterns for specific device types

Performance Issues

  • Increase --client-timeout for large libraries
  • Process in smaller batches by date range (using archive/upload workflow)

See Also