Skip to content

Commit

Permalink
docs: 馃摑 updated readme for version system
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Jun 29, 2021
1 parent 80e0507 commit 4a29232
Showing 1 changed file with 12 additions and 0 deletions.
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,15 @@
Bonnie is a command aliasing tool with support for custom arguments and environment variables. If you have a super-long command that you have to run all the time, Bonnie is for you! Just define the command in `bonnie.toml` at the root of your project, and you're good to go!

```toml
version = "0.2.0"
[scripts]
short = "really long command..."
```

For example, if you're running `docker-compose` a lot, and you have a custom environment variables file, it's annoying to type out `docker-compose --env-file .my.env ...` every time you want to do something! Bonnie can shorten this easily!

```toml
version = "0.2.0"
[scripts]
dc = "docker-compose --env-file .my.env %%"
```
Expand All @@ -23,6 +25,7 @@ The double percent sign (`%%`) at the end tells Bonnie to append any arguments y
You can even insert custom arguments into custom places in a custom order!

```toml
version = "0.2.0"
[scripts]
greet.cmd = "echo \"Greetings %lastname. I see your first name is %firstname?\""
greet.args = [
Expand All @@ -36,6 +39,7 @@ Now if you run `bonnie greet Donald Knuth` you should get `Greetings Knuth. I se
Environment variables can also be interpolated and sourced from specific files, like `.env`:

```toml
version = "0.2.0"
env_files = [
".env"
]
Expand Down Expand Up @@ -83,16 +87,20 @@ Just replace `[VERSION]` with the latest version (see the [releases page](https:
Bonnie is a simple command-line interface that looks for a `bonnie.toml` file in whatever directory you run the command in. All configuration is defined in there. If you want to put your config file somewhere else, or name it something else, see _Using a custom config file_ below. A basic Bonnie config file should look like this:

```toml
version = "0.2.0"
[scripts]
```

*Note: since v0.2.0, all Bonnie configuration files must contain a `version` tag.*

You can define all your command aliases, which Bonnie calls _scripts_ under the `[scripts]` heading. This file uses TOML, which is like JSON, but much easier to read for humans. You can learn more about it and the syntax it supports at [toml.io](https://toml.io). If you use any invalid TOML syntax or you don't define scripts properly in your config, Bonnie will tell you straight away, without trying to run the command you specified, so don't worry about something blowing up!

### Command with arguments

Bonnie supports inserting arguments into commands. This requires you to use the following syntax in `bonnie.toml`:

```toml
version = "0.2.0"
[scripts]
greet.cmd = "echo \"Greetings %lastname. I see your first name is %firstname?\""
greet.args = [
Expand All @@ -112,6 +120,7 @@ As yet, Bonnie doesn't support optional arguments or default values, but hopeful
Sometimes, you'll want to add a value of an environment variable into a Bonnie command, for example if you've got a variable `$APP_PORT` that defines which port your app runs on and you need to use that in an alias. Bonnie fully supports environment variable interpolation by using long-from notation and the `env_vars` key, just as you would with arguments:

```toml
version = "0.2.0"
[scripts]
interpolation.cmd = "echo \"%GREETING %firstname!\""
interpolation.args = [
Expand All @@ -133,6 +142,7 @@ GREETING="Hello, my dear friend" bonnie interpolation Donald
However, especially in complex projects, environment variables are very often stored in files like `.env`. Bonnie can load these natively with no extra work by using the `env_files` key in `bonnie.toml`:

```toml
version = "0.2.0"
env_files = [
".env"
]
Expand All @@ -156,6 +166,7 @@ Now, as long as `.env` exists, Bonnie will interpolate `$GREETING` without any e
Many of the commands you specify won't need arguments, they'll just be simple aliases. These can be specified trivially by just writing a key-value pair:

```toml
version = "0.2.0"
[scripts]
foobar = "echo Hello World"
```
Expand All @@ -167,6 +178,7 @@ You don't need `.cmd` or `.args`, you can just define it as `foobar`, where that
There are a lot of use cases where you'd want any arguments you provide to be appended to the end of a Bonnie script (this is the default behavior of NPM and Yarn scripts). You can do this easily in Bonnie by using shorthand syntax and adding a `%%` to the end of the command like so:

```toml
version = "0.2.0"
[scripts]
dc = "docker-compose --env-file .my.env %%"
```
Expand Down

0 comments on commit 4a29232

Please sign in to comment.