Image Vault is a command-line tool designed for organizing photo libraries in a deterministic way. It calculates the path for each photo based on its metadata and a configured template. Importing the same photo multiple times will always result in the same path, so duplicate files won't be added to the library. It's also possible to check library integrity (verifying all files are in place) and fix any inconsistencies.
mkdir Photos && cd Photos # Create a new directory for your photos
imv init # Initialize a new photo library
imv import <path_to_photos> # Import photos into the library
imv verify --fix # Verify the library integrity and fix any issues
imv cleanup # Clean up empty directories in the library
To install Image Vault, use the following command:
go install github.com/askolesov/image-vault/cmd/imv@latest
Alternatively, you can build from source (see Building from Source).
Image Vault requires exiftool to be installed on your system for handling photo metadata. Below are instructions for installing exiftool on different operating systems:
To install exiftool on Linux, you can use the package manager for your distribution. For example, on Ubuntu, you can use:
sudo apt install libimage-exiftool-perl
To install exiftool on macOS using Homebrew, first ensure you have Homebrew installed, then run:
brew install exiftool
To install exiftool on Windows, you can:
- Download the Windows executable from the official ExifTool website
- Or use Chocolatey package manager:
choco install exiftool - Or use Scoop package manager:
scoop install exiftool
Image Vault offers several commands to manage your photo library efficiently. Here are the main commands and their usage:
To initialize a new Image Vault photo library in the current directory:
imv init
This command creates a configuration file (image-vault.yaml) in the current directory, setting up the structure for your photo organization.
To import photos into your library:
imv import <path_to_photos>
This command processes the photos at the specified path, organizes them according to the configured template (which can include metadata like date taken, camera model, etc.), and imports them into the library.
To verify the integrity of your photo library:
imv verify
This command checks all photos in the library to ensure they are properly organized and match their expected locations based on their metadata and the configured template.
To verify and automatically fix any issues found:
imv verify --fix
To clean up empty directories in your photo library:
imv cleanup
This command removes empty directories that may have been left behind after moving or reorganizing photos, helping to keep your library structure clean and organized.
To show detailed metadata for a specific photo:
imv info <photo_path>
This command displays comprehensive metadata information for the specified photo, including camera settings, date taken, and other EXIF data.
To display version information about Image Vault:
imv version
Image Vault uses a YAML configuration file (image-vault.yaml) to customize its behavior. Here's an example of the default configuration:
# The template below forms the target path where images will be imported.
# It creates a structured directory based on image metadata and file information.
# template: Supports Go template syntax and Sprig functions.
# Available namespaces: fs, exif, hash
# For more details, run: image-vault info <file>
template: |-
{{- $make := or .Exif.Make .Exif.DeviceManufacturer "NoMake" -}}
{{- $model := or .Exif.Model .Exif.DeviceModelName "NoModel" -}}
{{- $dateTimeOriginal := and (any .Exif.DateTimeOriginal) (ne .Exif.DateTimeOriginal "0000:00:00 00:00:00") | ternary .Exif.DateTimeOriginal "" -}}
{{- $mediaCreateDate := and (any .Exif.MediaCreateDate) (ne .Exif.MediaCreateDate "0000:00:00 00:00:00") | ternary .Exif.MediaCreateDate "" -}}
{{- $date := or $dateTimeOriginal $mediaCreateDate "1970:01:01 00:00:00" | toDate "2006:01:02 15:04:05" -}}
{{- $mimeType := .Exif.MIMEType | default "unknown/unknown" | splitList "/" | first -}}
{{$make}} {{$model}} ({{$mimeType}})/{{$date | date "2006"}}/{{$date | date "2006-01-02"}}/{{$date | date "2006-01-02_15-04-05"}}_{{.Hash.Md5Short}}{{.Fs.Ext | lower}}
# skipPermissionDenied: Controls whether to skip files and directories with permission denied errors.
skipPermissionDenied: true
# ignore: List of file paths to ignore (supports .gitignore patterns).
ignore:
- "image-vault.yaml"
- ".*"
# sidecarExtensions: List of file extensions for sidecar files.
sidecarExtensions:
- ".xmp"
- ".yaml"
- ".json"
# ignoreFilesInCleanup: List of files to ignore when determining if a directory is empty during cleanup.
ignoreFilesInCleanup:
- ".DS_Store"You can modify this configuration to suit your photo organization needs. The template field is particularly important as it determines how your photos will be organized in the library based on their metadata.
To build Image Vault from source:
-
Clone the repository:
git clone https://github.com/askolesov/image-vault.git -
Navigate to the project directory:
cd image-vault -
Build the project:
make buildThis will create the
imvbinary in thebuild/directory. -
(Optional) Install the binary:
make install
Contributions to Image Vault are welcome! Please feel free to submit pull requests, create issues, or suggest improvements.
Before submitting a pull request, please ensure that:
-
Your code passes all tests:
make test -
Your code passes the linter:
make lint -
You've added tests for any new functionality.