casey / casey/just

Feature request: include a descriptive paragraph when listing the behaviour of a Justfile

Open
#1,815 3 comments 1 reaction 0 assignees View on GitHub
Dominant language
Rust
Stars
35.8k
Forks
846
Avg merge
27m
Merged PRs (30d)
3

Description

One of the attractions of `just` is getting a quick summary of the recipes with `--list`. I would find this more useful if it included a brief description of the project. The way I achieve this at the moment is to add the following recipe as the first in the file, which simply lists all the comment lines at the start of the file before listing the recipes.

```Just
# Summarises the purpose of this file.
# This lists the comment lines of the file until the first line that does
# not start with a '#' character. Then it lists the targets of the file.
about:
@awk '/^#/ {print} !/^#/ {exit}' "{{justfile()}}"
@echo
@just --list
```

This might be accommodated with
- a new option (e.g. `just --about`) or
- by a setting that sets a default for `--list-heading` (e.g. set list-heading "My very awesome project")
- by having a more elaborate convention for marking out the project summary (e.g. doubled '#' marks) and extending `--list`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.