Puff is a CLI tool that manages configuration files of the apps you're developing. Typically, these configs live together with the source codes of your projects. They are often excluded from version control systems due to secrets that they may contain. Puff manages those files and stores them in one common location, making it easier to transer them to another dev machine. Your apps access the configuration files via symlinks that Puff creates.
For the .NET developers, these could be appsettings.json
files. For the
NodeJS developers, these could be .env
files. Often such files contain secrets
that you want to keep locally.
Puff is "noninvasive", meaning that your apps do not have to be adjusted to work with configuration files managed by Puff. The configuration files are just replaced with symlinks (to a location managed by Puff).
The tool is the most useful for those who are moving from one machine to another and want to keep their app configs with them.
Puff is a bit similar to what dotnet Secret Manager offers. However, the only similarity is the implementation of a general idea of keeping secrets out of the app's directory. The way Puff works is totally different from what dotnet Secret Manager does (also, Puff is not dotnet-only, it can be used with any project).
Note that Puff is useful only during the development process of your apps. If you app is installable, it should then store its configuration file(s) in some standard location as defined by the vendor of the operating system (like the XDG specification for Linux).
The files managed by Puff are stored in the following locations, depending on the operating system:
- 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 would be storing your projects' configs in folders stored in the
configs
directory. Each project would have its own separate folder in the
configs
directory.
Moving to another machine is more straightforward since all your app settings files (at least the ones you manage with Puff) are stored in one central location that you can transfer to the new machine.
The following is the typical usage of Puff:
- You have some code project, let's say under
/home/user/code/app1
. - You can enable management of config files in that project by Puff, as follows:
cd /home/user/code/app1
puff init # you'll be asked to provide a name for a new project
At this point, Puff knows about that project, and it is able to manage config files for it.
- Let's add some config file to our project
puff add appsettings.json # optionally add '-g' flag to add the file to .gitignore
If the appsettings.json
file is already present in the directory, the command
above would turn it into a puff-managed file. If the file does not exist, it
would be created as a puff-managed file.
The appsettings.json
file becomes a symlink pointing to a location managed by
Puff.
All the puff-managed projects have their config files stored in the central directory making it easy to transfer the files to another dev machine if you need to do so.
To move the config files to another machine, copy the configs
directory and put it in the appropriate
location (depending on your operating system) on the target
machine.
Do not copy the config.json
file that can be found alongside the configs
directory. This file is normally unique per machine. It makes sense to copy it
(and place it alongside the configs
directory on the target machine) only if
all of your Puff-managed projects are in the exact same locations on the
target machine as they are on the source machine. Otherwise, just leave the
config.json
in the source machine.
It would be nice to have commands such as
puff export/import
to make it easier to move the configs. It could be added in the future (also by you, in a PR ;))
When the configs
directory is there (and Puff is installed) on the new
machine, you can initialize your projects, just like you initially did it on the
first machine. This time, however, Puff will "see" that there are some
unassociated configs available, and for any puff init
command, that you
invoke, you would be asked if you want to associate one of the configs you copied
over with the project that you're initializing.
Here's an example of that:
## 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
Once you initialize the project on the new machine, Puff will bring in all the config files of that project.
Note that you can use puff --help
to learn how to use Puff. Each
subcommand has its own --help
(e.g. puff add --help
).
You can get the binary at the
Releases page. Extract the zip to
any directory in your $PATH
(it could be /usr/local/bin
on linux).
If you try to run the binary on a Mac from your terminal, you will most likely get a warning "puff cannot be opened because the developer cannot be verified." To get around that, open Finder in the location where you extracted Puff, right-click it and click Open. Then, click Open again in the pop-up that appears. From now on, you'll be able to run Puff from the terminal.
Note that GitHub Release binaries are published only for x86 architecture at the moment, which is non-ideal for machines like M1-based macs.
If you have Rust's cargo installed, you can install this package with:
cargo install puff
Cargo will build the puff binary and place it in the $HOME/.cargo
directory.
This is currently the best option if your computer's architecture is different than x86 (e.g., M1 macs)
Puff can manage only one-level depth of files in a project. For example, if
you initialize the following path as a Puff project - /home/user/code/app1
- you can
puff add
only files that are directly in that directory.
If you see a use case for lifting that limitation, feel free to create a Pull Request or create an issue for it.
You can install the app locally using:
git clone https://github.com/marcinjahn/puff
cd marcinjahn/puff
cargo install --path .
I use cargo-release to release new versions of Puff to crates.io.
# PATCH
cargo release patch --execute --no-confirm
#MINOR
cargo release minor --execute --no-confirm
#MAJOR
cargo release major --execute --no-confirm