P

The problem

It can often take several minutes just to figure out how to start working on something.

Every project is different, but damn near every project comes with a set of development commands or scripts to run common actions. And if it doesn’t, then it probably should.

Different languages, people, and tools accomplish this in different ways. Some projects use the good ol’ Makefile, while others use package.json “scripts”, bash scripts, rake, fabric, and so on and so on…

The solution

Running p will show you which commands are available for the project you are on.

For example:

$ cd project
$ p
Usage: p [OPTIONS] COMMAND [ARGS]...

Options:
  --version
  --list
  --help     Show this message and exit.

Commands:
  mypy        Using: ./scripts/mypy
  pre-commit  Using: ./scripts/pre-commit
  setup       Using: pipenv sync --dev
  test        Using: ./scripts/test

It does this by discovering scripts and commands that already exist within the project, and by adding automatically inferred commands for known package managers or tools.

P is not a project requirement or dependency -- it is a personal tool. Nothing in your project should depend on p, but rather conform to p-friendly standards which are usable with or without p itself.

Ideally, p will “just work”. But if not, it is often in your project’s best interest to design a developer experience that would work if someone were using p. That is – script out some of the most commonly used actions for your project (install, test, deploy, etc.), and put them in a uniform place where contributors can easily figure out how to use them. P is simply a small abstraction layer to make it even easier yet for people that use it.

Install it for yourself

Don't add it to a project. Add it to your machine, system-wide or user-wide.

$ pip3 install -U git+https://github.com/dropseed/p.git#egg=p

Project commands

Local scripts

P will automatically find executable scripts (with no file extension) in ./scripts or ./bin. The filename will be added as a command so that they can simply be run by doing p {script-name}.

$ tree scripts/
scripts/
├── compile-assets
├── load-fixtures
├── pre-commit
├── setup
├── start-postgres
├── test
└── work

Will result in:

$ p
Usage: p [OPTIONS] COMMAND [ARGS]...

Options:
  --version
  --list
  --help     Show this message and exit.

Commands:
  compile-assets  Using: ./scripts/compile-assets
  load-fixtures   Using: ./scripts/load-fixtures
  pre-commit      Using: ./scripts/pre-commit
  setup           Using: ./scripts/setup
  start-postgres  Using: ./scripts/start-postgres
  test            Using: ./scripts/test
  work            Using: ./scripts/work

Makefile

If there is a Makefile in your project, p will automatically parse .PHONY and make those commands available via p. So if you have make test, it will also be available to p users via p test.

package.json scripts

Entries in your package.json "scripts" will automatically be mapped to p commands.

For example:

{
  "scripts": {
    "start": "react-scripts start"
  }
}

Would result in:

Usage: p [OPTIONS] COMMAND [ARGS]...

Options:
  --version
  --list
  --help     Show this message and exit.

Commands:
  install  Using: yarn install
  start    Using: npm run start

Inferred commands

P will automatically add commands for known package managers. These can be overridden by providing your own script of the same name in one of the recognized locations. So, for example, if you want contributors to use something more specific than a regular yarn install, just add an “install” script to package.json.

package.json

• npm install as p install

yarn.lock

• yarn install as p install

.terraform or terraform.tfstate

• terraform init as p install
• terraform apply as p deploy

Pipfile.lock

• pipenv sync --dev as p install

combine.yml

• combine work as p work

Cartfile or Cartfile.resolved

• carthage update as p install

Gopkg.toml or Gopkg.lock

• dep ensure as p install

Git hooks

P also provides automatically installation of git hooks, if you use commands named pre-commit or post-merge. On p install or p {git-hook-name} it will prompt you to install it into your local .githooks.

Chaining scripts together (advanced)

By default, the first match found for a command (ex. test) will be used. If you want to chain together multiple scripts, you can namespace them like test--anothertest. You can further specify when they are run by using the special --pre-- and --post-- separators (ex. test--pre--something). So the order of scripts will be:

• {command}--pre
• {command}--pre--{anything} - sorted alphabetically
• {command}
• {command}--{anything} - sorted alphabetically
• {command}--post
• {command}--post--{anything} - sorted alphabetically

Inspired by

• Dropseed’s project-cli (private)
• Flint Hills Design’s fhd-cli (private)
• https://github.com/github/scripts-to-rule-them-all
• https://github.com/bkeepers/strappydoo
• having too many projects