first commit

bin/README.md

@@ -0,0 +1,72 @@
+# `dev` command documentation
+
+## `dev` Command
+
+The `dev` command is a helper for using docker compose.
+
+For example, you can run a sql script via
+
+```bash
+dev sqlcmd -i ./data/funding_submission_lines.sql
+```
+
+assuming the file is located at `/db/data/funding_submission_lines.sql`
+
+Note that the `dev` command uses the `db` service, and so only has access to folders under the top-level `db` directory.
+
+## Set up `dev` command
+
+The `dev` command vastly simplifies development using docker compose. It only requires `ruby`; however, `direnv` and `asdf` will make it easier to use.
+
+It's simply a wrapper around docker compose with the ability to quickly add custom helpers.
+
+All commands are just strings joined together, so it's easy to add new commmands. `dev` prints out each command that it runs, so that you can run the command manually to debug it, or just so you learn some docker compose syntax as you go.
+
+1. (optional) Install `asdf` as seen in <https://asdf-vm.com/guide/getting-started.html>.
+
+   e.g. for Linux
+
+   ```bash
+   apt install curl git
+
+   git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.12.0
+
+   echo '
+   # asdf
+   . "$HOME/.asdf/asdf.sh"
+   . "$HOME/.asdf/completions/asdf.bash"
+   ' >> ~/.bashrc
+   ```
+
+2. Install `ruby` via `asdf` as seen here <https://github.com/asdf-vm/asdf-ruby>, or using whatever custom Ruby install method works for your platform.
+
+   e.g. for Linux
+
+   ```bash
+   asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git
+
+   # install version from .tool-versions file
+   asdf install ruby
+
+   asdf reshim ruby
+   ```
+
+   You will now be able to run the `./bin/dev` command.
+
+3. (optional) Install [direnv](https://direnv.net/) and create an `.envrc` with
+
+   ```bash
+    #!/usr/bin/env bash
+
+    PATH_add bin
+   ```
+
+   and then run `direnv allow`.
+
+   You will now be able to do `dev xxx` instead ov `./bin/dev xxx`.
+
+## Extras
+
+If you want to take over a directory or file in Linux you can use `dev ownit <path-to-directory-or-file>`.
+
+If you are on Windows or Mac, and you want that to work, you should implement it in the `bin/dev` file. You might never actually need to take ownership of anything, so this might not be relevant to you.