From 024cc168d70b8565bef24f30c9fce08608d733e6 Mon Sep 17 00:00:00 2001 From: sandroid Date: Thu, 9 Apr 2026 00:19:49 +0200 Subject: [PATCH] ci: enforce consistent markdown formatting with rumdl --- .github/workflows/ci.yaml | 6 ++++++ .pre-commit-config.yaml | 4 ++++ .rumdl.toml | 26 ++++++++++++++++++++++++++ AGENTS.md | 37 +++++++++++++++++++++++++++---------- CONTRIBUTING.md | 35 ++++++++++++++++++++++++----------- README.md | 28 +++++++++++++++++++++------- 6 files changed, 108 insertions(+), 28 deletions(-) create mode 100644 .rumdl.toml diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index ae89b58..d359a52 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -88,3 +88,9 @@ jobs: with: shfmt-version: 3.13.1 - run: shfmt --diff . + + rumdl-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - uses: rvben/rumdl@v0.1.68 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5d7e3c9..cae8c02 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -20,3 +20,7 @@ repos: (curl -fsSL https://wfxr.mit-license.org/2017/license.txt && echo) > ./LICENSE && git add ./LICENSE || { git checkout ./LICENSE && exit 1; } ' +- repo: https://github.com/rvben/rumdl-pre-commit + rev: v0.1.68 + hooks: + - id: rumdl-fmt # Auto-format and fail if issues remain diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 0000000..45fdc9c --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,26 @@ +# rumdl configuration file + +# Global configuration options +[global] + +# List of file/directory patterns to exclude from linting +exclude = [ + # Common directories to exclude + ".git", + ".github", +] + +# Respect .gitignore files when scanning directories +respect-gitignore = true + +# Disable rules +# MD033: inline HTML +disable = [ "MD033" ] + +# Rule-specific configurations + +[MD003] +style = "setext" # Heading style (atx, atx_closed, setext) + +[MD013] +line-length = 120 # Maximum characters per line diff --git a/AGENTS.md b/AGENTS.md index f17f137..62c98b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,8 @@ -# Repository Guidelines +Repository Guidelines +===================== -## Project Structure & Module Organization +Project Structure & Module Organization +--------------------------------------- `forgit` is a shell-based Git helper, so most changes land in a small set of files: @@ -13,7 +15,8 @@ When you add or rename a command, update the implementation, shell wrappers, completions, tests, and docs together. -## Build, Test, and Development Commands +Build, Test, and Development Commands +------------------------------------- There is no build step; validation is command-driven. @@ -22,19 +25,33 @@ There is no build step; validation is command-driven. - `bash forgit.plugin.sh`: verify Bash compatibility. - `zsh forgit.plugin.zsh`: verify Zsh compatibility. - `fish conf.d/forgit.plugin.fish`: verify Fish compatibility. +- `rumdl check .` CI runs these checks on macOS and Ubuntu. Keep local validation aligned with that workflow before opening a PR. -## Coding Style & Naming Conventions +Coding Style & Naming Conventions +--------------------------------- -Follow `.editorconfig`: UTF-8, LF endings, spaces for indentation, width 4, and no trailing whitespace. Match the existing shell style: prefer small helper functions, `local` variables inside functions, and descriptive private names such as `_forgit_extract_branch_name`. Keep command aliases and completion names consistent across shells. +Follow `.editorconfig`: UTF-8, LF endings, spaces for indentation, width 4, and no trailing whitespace. +Match the existing shell style: prefer small helper functions, `local` variables inside functions, +and descriptive private names such as `_forgit_extract_branch_name`. +Keep command aliases and completion names consistent across shells. -## Testing Guidelines +Testing Guidelines +------------------ -Tests use Bashunit and live in `tests/*.test.sh`. Name new files after the behavior under test, such as `worktree.test.sh` or `checkout.test.sh`. Source `bin/git-forgit` in tests and exercise helpers directly when possible. Add or update tests for behavior changes, especially parsing, selection, and cross-shell integration. +Tests use Bashunit and live in `tests/*.test.sh`. +Name new files after the behavior under test, such as `worktree.test.sh` or `checkout.test.sh`. +Source `bin/git-forgit` in tests and exercise helpers directly when possible. +Add or update tests for behavior changes, especially parsing, selection, and cross-shell integration. -## Commit & Pull Request Guidelines +Commit & Pull Request Guidelines +-------------------------------- -Git history follows Conventional Commits: `feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`, and occasional scoped forms like `style(docs): ...`. Write messages around the behavior change and its reason, not just the implementation detail. +Git history follows Conventional Commits: `feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`, +and occasional scoped forms like `style(docs): ...`. +Write messages around the behavior change and its reason, not just the implementation detail. -Use the PR template. Before submitting, perform a self-review, update docs for user-visible changes, add tests when behavior changes, and report the shells and operating systems you verified. +Use the PR template. +Before submitting, perform a self-review, update docs for user-visible changes, add tests when behavior changes, +and report the shells and operating systems you verified. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index feff849..ea0e6d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,13 @@ -# Contributing to forgit +Contributing to forgit +====================== Thanks for your interest in contributing to `forgit`. -This document covers the repository-specific workflow for reporting issues and opening pull requests. For installation, usage, commands, and configuration, see [README.md](README.md). +This document covers the repository-specific workflow for reporting issues and opening pull requests. +For installation, usage, commands, and configuration, see [README.md](README.md). -## Before You Start +Before You Start +---------------- Before opening an issue or pull request, please make sure that you: @@ -12,7 +15,8 @@ Before opening an issue or pull request, please make sure that you: - use the latest released version of `forgit` - search existing issues and pull requests for duplicates -## Repository Map +Repository Map +-------------- These are the main places you will usually need to touch: @@ -22,7 +26,8 @@ These are the main places you will usually need to touch: - [`completions/`](completions): tab completions for zsh, bash, and fish - [`tests/`](tests): [bashunit](https://bashunit.typeddevs.com/) test suite -## Making Changes +Making Changes +-------------- When changing or adding behavior, prefer to follow existing command patterns already used in the repository. @@ -37,7 +42,8 @@ Please keep changes focused. Small pull requests are easier to review and usuall When possible, keep core logic testable by sourcing `bin/git-forgit` directly and calling helper functions from unit tests. -## Development Dependencies +Development Dependencies +------------------------ To run the same checks as CI, make sure these tools are available locally: @@ -45,6 +51,7 @@ To run the same checks as CI, make sure these tools are available locally: - `shellcheck` - `curl` - `bashunit` as `lib/bashunit` +- `rumdl` If `lib/bashunit` is not available yet, install it once with: @@ -52,7 +59,8 @@ If `lib/bashunit` is not available yet, install it once with: curl -s https://bashunit.typeddevs.com/install.sh | bash -s 0.31.0 ``` -## Local Validation +Local Validation +---------------- Before opening a pull request, run the checks that match the current CI workflow: @@ -63,11 +71,13 @@ bash forgit.plugin.sh zsh forgit.plugin.zsh fish conf.d/forgit.plugin.fish shfmt --write . +rumdl check . ``` In your pull request, report which shells and operating systems you tested. -## Commit Messages +Commit Messages +--------------- This repository uses [Conventional Commits](https://www.conventionalcommits.org), and pull requests are checked accordingly in CI. @@ -109,7 +119,8 @@ Document the repository-specific review, testing, and completion update expectations so new contributors do not have to infer them from old issues. ``` -## Pull Requests +Pull Requests +------------- Before submitting a pull request, make sure that you: @@ -119,9 +130,11 @@ Before submitting a pull request, make sure that you: - update documentation when the change is user-visible - summarize the pull request in terms of what changed and why -Please use the pull request description to give reviewers the context they need. A short explanation of the approach is useful, but the main focus should be the behavior change and its motivation. +Please use the pull request description to give reviewers the context they need. +A short explanation of the approach is useful, but the main focus should be the behavior change and its motivation. -## Maintainers +Maintainers +----------- - [@wfxr](https://github.com/wfxr) - [@cjappl](https://github.com/cjappl) diff --git a/README.md b/README.md index 78c2f10..2fd4723 100644 --- a/README.md +++ b/README.md @@ -122,11 +122,13 @@ apply = ["source"] ### Homebrew To install using brew + ```sh brew install forgit ``` Then add the following to your shell's config file: + ```sh # Fish: # ~/.config/fish/config.fish: @@ -143,11 +145,16 @@ Then add the following to your shell's config file: ### Arch User Repository -[AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages, maintained by the developers of forgit, are available. Install the [forgit](https://aur.archlinux.org/packages/forgit) package for the latest release or [forgit-git](https://aur.archlinux.org/packages/forgit-git) to stay up to date with the latest commits from the default branch of this repository. +[AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages, maintained by the developers of forgit, +are available. Install the [forgit](https://aur.archlinux.org/packages/forgit) package for the latest release or +[forgit-git](https://aur.archlinux.org/packages/forgit-git) to stay up to date with the latest commits from the default +branch of this repository. ### Completions -Forgit offers completions for all supported shells. Completions are automatically configured when installing forgit through Homebrew or the AUR. All other installation methods mentioned above require manual setup for completions. The necessary steps depend on the shell you use. +Forgit offers completions for all supported shells. Completions are automatically configured when installing forgit +through Homebrew or the AUR. All other installation methods mentioned above require manual setup for completions. +The necessary steps depend on the shell you use. #### Bash @@ -158,13 +165,18 @@ Forgit offers completions for all supported shells. Completions are automaticall #### Fish -- Put [`completions/git-forgit.fish`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish) in `~/.config/fish/completions/` to have fish tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `ga`. +- Put [`completions/git-forgit.fish`](https://github.com/wfxr/forgit/blob/main/completions/git-forgit.fish) in +`~/.config/fish/completions/` to have fish tab completion for `git forgit` and configured git aliases, as well as shell +command aliases, such as `ga`. #### Zsh -- Put [`completions/_git-forgit`](completions/_git-forgit) in a directory in your `$fpath` (e.g., `/usr/share/zsh/site-functions`) to have zsh tab completion for `git forgit` and configured git aliases, as well as shell command aliases, such as `forgit::add` and `ga`. +- Put [`completions/_git-forgit`](completions/_git-forgit) in a directory in your `$fpath` +(e.g., `/usr/share/zsh/site-functions`) to have zsh tab completion for `git forgit` and configured git aliases, as well +as shell command aliases, such as `forgit::add` and `ga`. -If you're having issues after updating, and commands such as `forgit::add` or aliases `ga` aren't working, remove your completions cache and restart your shell. +If you're having issues after updating, and commands such as `forgit::add` or aliases `ga` aren't working, remove your +completions cache and restart your shell. ```zsh > rm ~/.zcompdump @@ -219,7 +231,7 @@ You can use forgit as a sub-command of git by making `git-forgit` available in ` PATH="$PATH:$FORGIT_INSTALL_DIR/bin" ``` -*Some plugin managers can help do this.* +_Some plugin managers can help do this._ Then, any forgit command will be a sub-command of git: @@ -304,7 +316,9 @@ variables: | `FORGIT_ATTRIBUTES_PAGER` | `bat -l gitattributes --color always` _or_ `cat` | | `FORGIT_PREVIEW_PAGER` | Normal pager resolution* | -* If your pager is a TUI program (e.g., `diffnav`, `tig`), fzf preview panes will be blank because they run without a TTY. Set `FORGIT_PREVIEW_PAGER` to a non-interactive pager (e.g., `delta`) to fix this. When set, it overrides all other `FORGIT_*_PAGER` settings in fzf preview context. +* If your pager is a TUI program (e.g., `diffnav`, `tig`), fzf preview panes will be blank because they run +without a TTY. Set `FORGIT_PREVIEW_PAGER` to a non-interactive pager (e.g., `delta`) to fix this. When set, it +overrides all other `FORGIT_*_PAGER` settings in fzf preview context. ### FZF Options