gopass-migrate

Safely consolidate multiple gopass entries into one structured YAML entry with automatic backups and OTP protection.

Overview

gopass-migrate helps consolidate scattered entries into single entries with nested YAML structure while ensuring:

  • Backups are created before any changes

  • OTP entries are never touched

  • Source entries are never auto-deleted

  • Every step requires confirmation

Location: ~/atelier/_projects/personal/dotfiles-optimus/bin/gopass-migrate

Lines: 437

Created: 2026-03-18

Installation

# Option 1: Symlink to PATH
ln -sf ~/atelier/_projects/personal/dotfiles-optimus/bin/gopass-migrate ~/.local/bin/

# Option 2: Using stow (symlinks entire bin/)
stow -d ~/atelier/_projects/personal/dotfiles-optimus -t ~ bin

# Verify
gopass-migrate --help

Usage

Interactive Mode (Recommended)

gopass-migrate --interactive
# or just
gopass-migrate

Guides you through:

  1. Selecting source entries

  2. Specifying target path

  3. Previewing combined structure

  4. Confirming execution

Preview Mode (Dry Run)

gopass-migrate --preview source1 source2 target
gopass-migrate --preview v3/personal/housing/apt1 v3/personal/housing/apt2 v3/personal/housing/prospective

Shows what would happen without making changes.

Execute Mode

gopass-migrate --execute source1 source2 target

Actually performs the migration with confirmations.

Example Workflow

# 1. Audit to find consolidation candidates
gopass-audit v3/personal/housing/

# 2. Preview the migration
gopass-migrate --preview \
  v3/personal/housing/north-hills-1 \
  v3/personal/housing/north-hills-2 \
  v3/personal/housing/prospective

# 3. Execute if preview looks good
gopass-migrate --execute \
  v3/personal/housing/north-hills-1 \
  v3/personal/housing/north-hills-2 \
  v3/personal/housing/prospective

# 4. Verify the new entry
gopass show v3/personal/housing/prospective
gopass show v3/personal/housing/prospective north-hills-1.password

# 5. Archive old entries (manual step)
gopass mv v3/personal/housing/north-hills-1 archive/housing/north-hills-1
gopass mv v3/personal/housing/north-hills-2 archive/housing/north-hills-2

Safety Features

OTP Protection

The tool refuses to migrate:

  • Entries ending in -otp

  • Entries containing otpauth:// URIs

This protects gopass otp functionality.

Automatic Backups

Before any modification:

[INFO] Creating backups...
[INFO] Backing up: v3/personal/housing/north-hills-1
[OK] Backup saved: ~/.gopass-migration-backups/v3_personal_housing_north-hills-1_20260318-143022.txt

Backups stored in: ~/.gopass-migration-backups/

No Auto-Delete

Source entries are never automatically deleted.

After migration, you manually archive:

gopass mv v3/personal/old/entry archive/old/entry

Step-by-Step Confirmation

Every destructive action requires explicit y confirmation.

Combined Entry Structure

The tool creates entries like:

PRIMARY_SECRET_HERE
---
# From: v3/personal/housing/north-hills-1
north-hills-1:
  password: "original-secret-1"
  address: "123 North Hills Dr"
  rent: "2400"

# From: v3/personal/housing/north-hills-2
north-hills-2:
  password: "original-secret-2"
  address: "456 North Hills Ave"
  rent: "2200"

Access with dot notation:

gopass show v3/personal/housing/prospective north-hills-1.address
gopass show v3/personal/housing/prospective north-hills-2.rent

Handling OTP Pairs

If a source entry has an OTP pair (e.g., chase has chase-otp):

[WARN] Entry has OTP pair: v3/personal/banking/chase
[WARN] The OTP entry (v3/personal/banking/chase-otp) must remain separate.
Continue anyway? [y/N]:

The base entry can be migrated, but the -otp entry stays where it is.

Related