Skip to content

Generate a README.md inside the archive with creation details, install and restore instructions #4

Closed

Description

@coldsofttech

Summary

After creating an archive, BatchVault should also write a README.md into the archive output. It should tell anyone who finds the archive later (possibly years on, with no context) how it was made, how to get BatchVault, and exactly how to restore it.

Motivation

An archive is often opened long after it was created, by someone who may not know what BatchVault is or which options were used. A self-describing README removes the guesswork and makes the archive restorable without outside documentation.

Requirements

The generated README.md should contain:

1. How this archive was made

  • BatchVault version used and creation timestamp
  • The command/options used to create it (volume size, compression settings, encryption on/off, signed manifest on/off, include/exclude patterns, --update, etc.)
  • Number of source files, number of volumes, total size
  • Location/name of the manifest file

Never include secrets (passwords, keys, tokens). If encryption was used, state that a password/key is required, without revealing it.

2. How to install BatchVault

  • pip install batchvault, plus pipx and uv tool install alternatives
  • Required Python version (3.11.4+)
  • Mention of Docker image / GitHub Action as alternatives
  • Pin to the version used to create the archive, e.g. pip install batchvault==<version>

3. How to unarchive (specific to this archive)

  • A ready-to-run restore command tailored to how the archive was created, e.g. using the manifest path and an output folder
  • Flags/params that apply to this archive only, for example:
    • the decrypt password/key option, if encrypted
    • the signature/public-key option to verify the manifest, if signed
    • any other option required to restore correctly
  • How to verify the archive before restoring (verify), if available
  • Alternate restore entry points (from a folder, a single volume, a list of volumes)

Acceptance criteria

  • README.md is written automatically after a successful archive creation, in the archive output location
  • Content reflects the actual options used (encrypted/signed/split size, etc.), with no secrets
  • Restore command in the README works as written against that archive
  • Option to disable generation (e.g. --no-readme) and the README is not treated as an archive volume or break --update/verify
  • Documented in docs/ and CHANGELOG.md
  • Tests cover plain, encrypted and signed archives

Activity

  1. coldsofttech commented on Nov 14, 2026

    @coldsofttech
    OwnerAuthor

    Implemented in #10: pack now writes BATCHVAULT-README.md next to the manifest (how the archive was made, how to install the same version, and the exact restore and verify commands). --no-readme turns it off. It ships in 0.1.1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions