From ec0ac0b72800e3a90415cefecd5f15054b84974f Mon Sep 17 00:00:00 2001 From: marcinjahn Date: Mon, 7 Feb 2022 14:56:39 +0100 Subject: [PATCH] Improve README --- README.md | 66 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 38eb5d6..d85a8d7 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,21 @@ -# puff +# Puff [![CI](https://github.com/marcinjahn/puff/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/marcinjahn/puff/actions/workflows/ci.yml) -Puff is a CLI tool that solves the issue of storing app configuration files in -various directories (typically, they live in various code projects' folders) -making it difficult to move these files to another dev machine. Such -configuration files 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. Your apps access the configuration files via symlinks that puff -creates. +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 to yourself. +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). +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. @@ -24,33 +23,38 @@ and want to keep their app configs with them. Puff is a bit similar to what [dotnet Secret Manager](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-6.0&tabs=windows#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 how puff works is totally -different from what dotnet Secret Manager does (also, puff is not dotnet-only, it +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). + ## Configs location -The files managed by puff are stored in the following locations, depending on +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 +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 +files (at least the ones you manage with Puff) are stored in one central location that you can transfer to the new machine. ## Usage -The following is the typical usage of puff: +The following is the typical usage of Puff: 1. You have some code project, let's say under `/home/user/code/app1`. -2. You can enable management of config files in that project by puff, as +2. You can enable management of config files in that project by Puff, as follows: ```sh @@ -58,7 +62,7 @@ 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 +At this point, Puff knows about that project, and it is able to manage config files for it. 3. Let's add some config file to our project @@ -72,7 +76,7 @@ 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. +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 @@ -88,16 +92,16 @@ 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 +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 +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 +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. @@ -111,10 +115,10 @@ 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 +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 +Note that you can use `puff --help` to learn how to use Puff. Each subcommand has its own `--help` (e.g. `puff add --help`). ## Installation @@ -127,9 +131,9 @@ 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, +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. +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. @@ -152,7 +156,7 @@ Cargo will build the puff binary and place it in the `$HOME/.cargo` directory. ### Project subdirectories are not supported 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 +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 @@ -172,7 +176,7 @@ cargo install --path . ### Releases I use [cargo-release](https://github.com/crate-ci/cargo-release) to release new -versions of puff to [crates.io](https://crates.io/crates/puff). +versions of Puff to [crates.io](https://crates.io/crates/puff). ```sh # PATCH