Puff

Puff 是一个 CLI 工具，用于管理您正在开发的应用程序的配置文件。通常，这些配置文件与您的项目源代码一起存在。由于它们可能包含秘密，因此通常从版本控制系统中排除。Puff 管理这些文件，并将它们存储在一个共同的位置，这使得将它们传输到另一台开发机器变得更容易。您的应用程序通过 Puff 创建的符号链接访问配置文件。

对于 .NET 开发者，这些可能是 appsettings.json 文件。对于 NodeJS 开发者，这些可能是 .env 文件。通常此类文件包含您希望保留在本地的秘密。

Puff 是“非侵入式”的，这意味着您的应用程序无需调整以使用 Puff 管理的配置文件。配置文件只是被替换为符号链接（指向由 Puff 管理的位置）。

此工具对那些在不同机器之间迁移并希望保留其应用程序配置的人非常有用。

Puff 与 dotnet Secret Manager 提供的功能有些相似。然而，唯一的相似之处在于将秘密排除在应用程序目录之外的一般想法的实施。Puff 的工作方式与 dotnet Secret Manager 完全不同（此外，Puff 不仅仅用于 dotnet，它可以用于任何项目）。

请注意，Puff 仅在您的应用程序开发过程中有用。如果您的应用程序可安装，则应将其配置文件（s）存储在操作系统供应商定义的某些标准位置（如 Linux 的 XDG 规范）中。

配置文件位置

根据操作系统，Puff 管理的文件存储在以下位置：

• macOS: /Users/Alice/Library/Application Support/com.marcinjahn.puff/configs
• Linux: /home/alice/.config/puff/configs
• Windows: C:\Users\Alice\AppData\Roaming\marcinjahn\puff\configs

Puff 会将您的项目配置存储在 configs 目录下的文件夹中。每个项目在 configs 目录下都有自己的单独文件夹。

迁移到另一台机器更加简单，因为您所有应用程序的设置文件（至少是您使用 Puff 管理的文件）都存储在一个中央位置，您可以将其转移到新机器上。

使用方法

以下是 Puff 的典型使用方法

1. 您有一个代码项目，比如在 /home/user/code/app1 下。
2. 您可以使用 Puff 启用对该项目中配置文件的管理，如下所示

cd /home/user/code/app1
puff init # you'll be asked to provide a name for a new project

此时，Puff 已知道该项目，并能管理它的配置文件。

3. 让我们向我们的项目中添加一些配置文件

puff add appsettings.json # optionally add '-g' flag to add the file to .gitignore

如果 appsettings.json 文件已经存在于该目录中，上面的命令就会将其转换为 Puff 管理的文件。如果该文件不存在，则会创建一个 Puff 管理的文件。

appsettings.json 文件变成一个指向 Puff 管理位置的符号链接。

所有 Puff 管理的项目都将它们的配置文件存储在中央目录中，这使得在需要时轻松地将文件传输到另一台开发机器变得容易。

将配置传输到另一台机器

要将配置文件移动到另一台机器，复制 configs 目录 并将其放在目标机器上适当的位置（根据您的操作系统而定）。

不要 复制与 configs 目录一起找到的 config.json 文件。此文件通常每台机器都是唯一的。只有在您的所有 Puff 管理的项目在目标机器上的位置与源机器上完全相同的情况下，才需要复制它（并将它与 configs 目录一起放置在目标机器上）。否则，只需在源机器上保留 config.json 即可。

拥有如 puff export / import 这样的命令将使迁移配置变得更加容易。这可能在将来添加（也可能是由您，通过 PR 实现）

当 configs 目录在新机器上存在（且已安装 Puff）时，您可以像在第一台机器上那样初始化您的项目。然而，这次，Puff 将“看到”有一些未关联的配置可用，对于您调用的任何 puff init 命令，都会询问您是否要将您复制过来的某个配置与您正在初始化的项目关联起来。

以下是一个示例

## On a new machine
git clone some-repo/app1
cd app1
puff init # you'll be asked if you want to create a fresh project or associate it with one of the existing configs

一旦在新机器上初始化了项目，Puff 将将该项目所有配置文件带入。

请注意，您可以使用 puff --help 来了解如何使用 Puff。每个子命令都有自己的 --help（例如 puff add --help）。

安装

GitHub 发布

您可以从 发布 页面获取二进制文件。将 zip 文件解压到您的 $PATH 中的任何目录（在 Linux 上可能是 /usr/local/bin）。

如果您尝试在终端中从Mac上运行该二进制文件，您很可能会收到一个警告：“puff无法打开，因为开发者无法验证。”要绕过这个问题，请在您提取Puff的位置打开Finder，右键单击它，然后点击打开。然后，在弹出的窗口中再次点击打开。从现在起，您将能够从终端运行Puff。

请注意，GitHub发行版的二进制文件目前仅针对x86架构发布，这对基于M1的mac等机器来说不是最佳选择。

Cargo

如果您已安装Rust的cargo，您可以使用以下命令安装此软件包

cargo install puff

Cargo将构建puff二进制文件并将其放置在$HOME/.cargo目录。

如果您计算机的体系结构不同于x86（例如，M1 mac），这目前是最佳选择

限制

不支持项目子目录

Puff只能管理项目中的单层深度文件。例如，如果您将以下路径初始化为Puff项目 - /home/user/code/app1 - 您只能添加直接在该目录中的文件。

如果您认为需要取消此限制，请随时创建Pull Request或创建相关的问题。

开发

您可以使用以下命令在本地安装应用程序

git clone https://github.com/marcinjahn/puff
cd marcinjahn/puff
cargo install --path .

发布

我使用cargo-release将Puff的新版本发布到crates.io。

# PATCH
cargo release patch --execute --no-confirm

#MINOR
cargo release minor --execute --no-confirm

#MAJOR
cargo release major --execute --no-confirm

主页

marcinjahn.com/projects/puff.html