https://github.com/paldepind/projectdo
Context-aware single-letter project commands to speed up your terminal workflow.
https://github.com/paldepind/projectdo
cli command-line fish-plugin
Last synced: about 1 year ago
JSON representation
Context-aware single-letter project commands to speed up your terminal workflow.
- Host: GitHub
- URL: https://github.com/paldepind/projectdo
- Owner: paldepind
- License: gpl-3.0
- Created: 2019-03-15T20:23:10.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-04-09T16:55:07.000Z (about 1 year ago)
- Last Synced: 2025-04-09T17:42:14.137Z (about 1 year ago)
- Topics: cli, command-line, fish-plugin
- Language: Shell
- Homepage:
- Size: 159 KB
- Stars: 72
- Watchers: 2
- Forks: 7
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awsm.fish - Projectdo - Context-aware single-letter abbreviations to build, run, and test any project (Plugins)
README
Context-aware single-letter project commands to speed up your command-line workflow.
*   🏗   b to build/compile any project.
*   🚀   r to run/start any project.
*   🧪   t to test any project.
https://user-images.githubusercontent.com/521604/231857437-12c14aff-585d-4817-8f44-59b40ecc32e0.mov
* **Supports 10+ build and project tools** – Bun, CMake, Cabal, Cargo, Go,
Leiningen, Mage, Maven, Meson, Poetry, Stack, Tectonic, make, npm, yarn and .NET.
[More details](#supported-tools-and-languages).
* **Portable** – Dependency free portable POSIX shell script. Supports Linux,
macOS, WSL, etc.
* **Shell Integration** – Works with aliases in any shell and for the Fish
shell through a [Fish plugin](#fish-plugin).
* **Simple** – Easy to extend with support for new tools.
## What
`projectdo` is a command-line program that executes project actions (such as
build, run, test, etc.) with the appropriate tool for current project in the
working directory. The appropriate tool and the current project root is
intelligently detected based on the context where `projectdo` is executed. For
instance, `projectdo test` runs `cargo test` if a `Cargo.toml` is found and
`npm test` if a `package.json` file is found.
By combining `projectdo` with shell aliases or shell abbreviations project
commands can be run in any project with less typing. As an example, with the
alias `alias b='projectdo build'` one can build any project simply by typing
b+enter.
## Install
`projectdo` can be installed through a number of package managers or by
manually downloading the shell script.
### Homebrew
`projectdo` can be installed with Homebrew on macOS and Linux.
```
brew install paldepind/tap/projectdo
```
### AUR (Arch Linux)
The [AUR package](https://aur.archlinux.org/packages/projectdo) can be installed manually or using an AUR helper.
```sh
yay -S projectdo
```
### npm
`projectdo` is not related to Node.js or JavaScript, but npm works perfectly
fine for distributing shell scripts and can be a handy installation method if
you're already using npm:
```sh
npm i -g projectdo
```
### From source
Download the script and place it somewhere in your path. For instance if
`~/bin` is in your path:
```
curl https://raw.githubusercontent.com/paldepind/projectdo/main/projectdo -o ~/bin/projectdo
chmod +x ~/bin/projectdo
```
#### From repository
Clone the project repository:
```sh
git clone https://github.com/paldepind/projectdo; cd projectdo
```
Install it with this command:
```sh
make install
# Or to uninstall
make uninstall
```
## Shell integration
For the Fish shell use [the Fish plugin](#fish-plugin). For Bash and Zsh setup
[shell aliases](#aliases).
### Fish Plugin
`projectdo` ships with a plugin for the Fish shell. The plugin includes
auto-completion and functions for use with Fish's abbreviation feature.
The Fish plugin can be installed manually or with
[Fisher](https://github.com/jorgebucaran/fisher):
```
fisher install paldepind/projectdo
```
The plugin exposes four shell functions that should be configured with
abbreviations as desired. For instance:
```
abbr -a b --function projectdo_build
abbr -a r --function projectdo_run
abbr -a t --function projectdo_test
abbr -a p --function projectdo_tool
```
With the above `t` will expand to `cargo test`, `p` will expand to `cargo`,
etc. depending on the project.
_Note that you need to have the script in your path in order for the Fish plugin to work!_
### Aliases
`projectdo` can be configured with shell aliases in any shell. For instance:
```sh
alias t='projectdo test'
alias r='projectdo run'
alias b='projectdo build'
alias p='projectdo tool'
```
## Usage
**Note**: When executed with the `-d` flag `projectdo` performs a dry run and
only prints information about what it would do without actually doing anything.
It is a good idea to do a dry run when using `projectdo` in a project for the
first time to verify that it does the right thing.
```
Usage: projectdo [options] [action] [tool-arguments]
Options:
-h, --help Display this help.
-n, -d, --dry-run Do not execute any commands with side-effects.
-q, --quiet Do not print commands as they are about to be executed.
-v, --version Display the version of the program.
Actions:
build, run, test Build, run, or test the current project.
tool Invoke the guessed tool for the current project.
Tool arguments:
Any arguments following [action] are passed along to the invoked tool.
```
## Supported tools and languages
**Note:** If a tool you are interested in is not supported please open an issue or a pull
request.
| Tool | Language | Detected by | Commands |
|-----------------|------------------|--------------------------------------------|--------------------------------------------------------|
| Cargo | Rust | `Cargo.toml` | `cargo build`
`cargo run`
`cargo test` |
| Poetry | Python | `pyproject.toml` with `[tool.poetry]` | `poetry build`
run n/a
`poetry run pytest` |
| CMake | C, C++ and Obj-C | `CMakeLists.txt` | `cmake --build . --target test` |
| Meson | C, C++, etc. | `meson.build` | `meson compile`
run n/a
`meson test` |
| npm | JavaScript, etc. | `package.json` | `npm build`
`npm start`
`npm test` |
| yarn | JavaScript, etc. | `package.json` and `yarn.lock` | `yarn build`
`yarn start`
`yarn test` |
| pnpm | JavaScript, etc | `package.json` and `pnpm-lock.yaml` | `pnpm build`
`pnpm start`
`pnpm test` |
| bun | JavaScript, etc | `package.json` and `bun.lock`/`bun.lockb` | `bun build`
`bun start`
`bun test` |
| Maven | Java, etc. | `pom.xml` | `mvn compile`
run n/a
`mvn test` |
| Leiningen | Clojure | `project.clj` | `lein test` |
| Cabal | Haskell | `*.cabal` | `cabal build`
`cabal run`
`cabal test` |
| Stack | Haskell | `stack.yaml` | `stack build`
`stack run`
`stack test` |
| nix (flake) | nix | `flake.nix` | `nix build`
`nix run`
`nix flake check` |
| nix (non-flake) | nix | `default.nix` | `nix-build` |
| make | Any | `Makefile` | `make`
`make test/check` |
| just | Any | `justfile` | `just build`
`just run`
`just test` |
| Mage | Go | `magefile.go` with a `test`/`check` target | `mage test/check` |
| Go | Go | `go.mod` | `go test` |
| Tectonic | LaTeX | `Tectonic.toml` | `tectonic -X build` |
| .NET | C# and F# | `*.csproj`, `*.fsproj` or `*.sln` | `dotnet build`
`dotnet run`
`dotnet test` |
| Shell script | Any | `build.sh` | `sh -c build.sh` |