snapstash

English | 简体中文

一个轻量 CLI：将 Git index（已暂存变更）或目录快照为 .snapstash/.backup，可选 AES-256-GCM 加密。

支持复制粘贴：备份文件为纯文本，可复制到新项目后恢复。

安装

npm i -g snapstash

或者无需全局安装：

npx snapstash

快速开始

1. 初始化配置（语种 + 加密引导 + gitignore）：

snapstash init
snapstash keygen

2. 备份当前 Git index（已暂存变更）：

snapstash

3. 恢复到当前目录：

snapstash r

用法

# 默认：备份 Git index（已暂存） -> .snapstash/.backup
snapstash

# 使用密码加密（可选）
snapstash b --pw 123

# 备份目录而不是 Git index
snapstash b --root ./my-folder

# 恢复到当前目录（可用 --root 指定目录）
snapstash r

# 查看备份信息
snapstash i --pw 123

# 打印完整 JSON 配置说明
snapstash schema
snapstash sc

# 复制备份文本到剪贴板
snapstash b --clipboard

# 使用指定配置文件
snapstash b --config ./config.json

# 创建 .snapstash 模板并写入 .gitignore（如果是 git 仓库）
snapstash init

命令与参数

snapstash / snapstash b（备份）

snapstash b [options]

参数：

• --output, -o <file> 输出文件（默认 .snapstash/.backup）
• --config <file> 指定配置文件
• --pw <password> 加密密码（为空则仅压缩）
• --pw-env <ENV> 密码环境变量名（默认 SNAPSTASH_PW）
• --no-concurrency 禁用并发（单线程）
• --threads <n> 线程数
• --bigfile-mb <n> 大文件阈值（MB）
• --total-size-mb <n> 总大小阈值（MB）
• --file-count-threshold <n> 文件数量阈值
• --clipboard, --c 复制到剪贴板
• --no-progress 关闭进度日志
• --root, --dir <path> 备份目录（文件系统模式）
• --from <stash|fs> 指定来源（默认 stash）

snapstash r（恢复）

snapstash r [options]

参数：

• --input, -i <file> 输入文件（默认 .snapstash/.backup）
• --config <file> 指定配置文件
• --root, --dir <path> 恢复目录（默认当前目录）
• --pw <password> 解密密码
• --pw-env <ENV> 密码环境变量名（默认 SNAPSTASH_PW）
• --no-progress 关闭进度日志

snapstash i（信息）

snapstash i [options]

参数：

• --input, -i <file> 输入文件（默认 .snapstash/.backup）
• --root, --dir <path> 备份所属目录（默认当前目录）
• --pw <password> 解密密码
• --pw-env <ENV> 密码环境变量名（默认 SNAPSTASH_PW）

snapstash schema / snapstash sc（配置说明）

snapstash schema

打印完整的 JSON 配置说明模板。key 保持不变，value 为当前 key 的含义说明。

snapstash init（初始化）

snapstash init

交互步骤：

1. 选择语种（en/zh）
2. 若配置已存在，确认是否覆盖
3. 选择加密方式：none / symmetric / asymmetric
4. 输入直接写入的秘钥，或改用 env 名
5. 可选将 env 的实际值自动写入 shell rc 文件

配置（.snapstash/config.json）

在项目根目录放置 .snapstash/config.json。如果不存在，会回退到 ~/.snapstash/config.json 作为全局配置（只读）；备份输出仍写入 [pwd]/.snapstash/.backup（或 --root）。

{
  "version": 1,
  "lang": "en",
  "encryption": {
    "algorithm": "x25519",
    "publicKey": "x25519-pub:<base64url-32-byte-public-key>",
    "privateKeyEnv": "SNAPSTASH_X25519_PRIVATE"
  },
  "concurrency": {
    "threads": 8
  },
  "excludes": [".snapstash/", "node_modules/", "dist/", "*.log"]
}

• 对称模式推荐显式写法是：password / passwordEnv 搭配 encryption.algorithm: "aes-256-gcm"
• 非对称模式现在支持一份配置同时完成加密/解密：用 encryption.publicKey / encryption.publicKeyEnv 提供备份公钥，用 encryption.privateKey / encryption.privateKeyEnv 提供恢复/查看私钥
• key/keyEnv 仍兼容，作为旧版非对称密钥字段继续可用；password/passwordEnv 也继续兼容，且仍适合作为对称加密密码字段
• encryption.algorithm 是更推荐的显式开关：x25519 表示非对称，aes-256-gcm 表示对称
• encryption.type 仍兼容保留；当 algorithm 存在时，Snapstash 以 algorithm 为准
• 如果省略 algorithm，Snapstash 会自动推断模式：存在 publicKey / privateKey* 时走非对称，只写 password 时走 AES-256-GCM
• encryption.keyType 默认是 public；在非对称模式下，Snapstash 支持紧凑 raw key、JWK 或 PEM，并会尽量自动识别传入的是公钥还是私钥
• encryption.algorithm 当前支持 aes-256-gcm 和 x25519；其中 x25519 实际采用 X25519 + AES-256-GCM 混合加密
• --pw 和 --pw-env 在对称/非对称模式下都仍然拥有最高优先级，可临时覆盖配置
• 非对称模式下，backup 优先读取配置中的公钥/公钥环境变量，restore/info 优先读取私钥/私钥环境变量
• concurrency 控制并发压缩；未显式配置的子项会回落到默认值：enabled=true、threads=4、bigFileMB=1、totalSizeMB=5、fileCountThreshold=30
• 你可以只覆盖一个并发子项，例如 {"concurrency":{"threads":8}}
• totalSizeMB 当总原始大小达到阈值时触发并发
• excludes 为相对路径匹配，dir/ 表示目录，*.log 为简单通配
• lang/language 支持 en（默认）或 zh，用于 help 与日志
  • 词条文件位于 i18n/en.json 和 i18n/zh.json

X25519 密钥格式：

• 推荐公钥：x25519-pub:<base64url>，其中 <base64url> 是 32 字节 raw public key（无 padding 时 43 个字符）
• 推荐私钥：x25519-priv:<base64url>，其中 <base64url> 是 32 字节 raw private key（无 padding 时 43 个字符）
• snapstash keygen 会直接生成这种紧凑格式，不是把整段 PEM 再做一层 base64
• ssh-ed25519 ...、ssh-rsa ... 这类 OpenSSH 公钥不是 X25519，不能直接用于 Snapstash
• 兼容公钥：PEM/SPKI（-----BEGIN PUBLIC KEY-----）或带 x 的 JWK OKP/X25519
• 兼容私钥：PEM/PKCS#8（-----BEGIN PRIVATE KEY-----）或带 d（可选 x）的 JWK OKP/X25519
• 生成一组密钥： snapstash keygen
• 把现有 X25519 PEM 公钥转成推荐格式： snapstash keygen --from-public ~/.ssh/snapstash-x25519-public.pem
• 把现有 X25519 PEM 私钥转成推荐格式： snapstash keygen --from-private ~/.ssh/snapstash-x25519-private.pem

配置读取顺序：

1. --config <file>
2. [project]/.snapstash/config.json
3. ~/.snapstash/config.json

说明

• 默认备份来源为 Git index（已暂存变更）。使用 --root 或 --from fs 备份目录。
• 密码或密钥材料可通过 --pw、keyEnv/passwordEnv 指定的环境变量或默认环境变量 SNAPSTASH_PW 提供；未提供时只压缩（base64 + brotli）。
• 对称模式使用 AES-256-GCM + scrypt；非对称模式使用 X25519 + AES-256-GCM。
• 非对称方案选择 X25519，因为它在保证现代安全性的同时，只需要额外写入 32 字节临时公钥和少量 AEAD 元数据，产物体积明显小于 RSA 这类包裹式方案。紧凑密钥配置格式不改变压缩参数，也不会增加备份头部大小。
• snapstash i 可查看加密备份的元信息（version、createdAt、repoRoot、head、payloadEncoding）。
• 使用 snapstash schema、snapstash sc 或 snapstash config-schema 可打印当前语言下的完整 JSON 配置说明模板。
• snapstash init 会创建 .snapstash 模板并在 Git 仓库中加入 .gitignore。
• --clipboard/--c 复制备份文本到剪贴板。
• 默认输出进度日志，可用 --no-progress 关闭。

友情链接

• Nano Banana 2｜极速图片生成
• Sora 2｜文本转视频体验
• Grok Video｜爆款 AI 视频
• Ricebowl AI｜一站式 AI 视频平台