pr-tools: Decentralized git pull request and code review flows

[ bsd3, development, git, library, program ] [ Propose Tags ] [ Report a vulnerability ]

A set of command-line tools for managing descentralized git pull requests and code review workflows. These tools help with creating PR snapshots, sending notifications to Slack, tracking approvals, merging PRs, reviewing changes, and viewing annotated diffs.

  • pr-snapshot: Generate a Markdown snapshot of the PR including commits and diff summary.

  • pr-send: Send the PR snapshot to a Slack channel for review.

  • pr-track: Track PR approvals, status, and commit history.

  • pr-merge: Merge approved PRs with various strategies and update changelog.

  • pr-review: Interactive code review tool with comment management.

  • pr-view: View annotated diffs with review comments.

  • pr-fix: Fix comments received in a review.

  • pr-init: Interactively generate configuration file for pr-tools.


[Skip to Readme]

Modules

  • PRTools
    • PRTools.CommentFormatter
    • PRTools.CommentRenderer
    • PRTools.Config
    • PRTools.PRState
    • PRTools.ReviewState
    • PRTools.Slack

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0
Change log CHANGELOG.md
Dependencies aeson (>=2.2.3 && <2.3), base (>=4.14 && <5), bytestring (>=0.11.5 && <0.12), case-insensitive (>=1.2.1 && <1.3), containers (>=0.6.7 && <0.7), Diff (>=1.0.2 && <1.1), directory (>=1.3.8 && <1.4), extra (>=1.8 && <1.9), filepath (>=1.4.301 && <1.5), Glob (>=0.10.2 && <0.11), http-client (>=0.7.19 && <0.8), http-client-tls (>=0.3.6 && <0.4), http-types (>=0.12.4 && <0.13), optparse-applicative (>=0.19.0 && <0.20), pr-tools, process (>=1.6.19 && <1.7), split (>=0.2.5 && <0.3), temporary (>=1.3 && <1.4), text (>=2.0.2 && <2.1), time (>=1.12.2 && <1.13), uuid (>=1.3.16 && <1.4), yaml (>=0.11.11 && <0.12) [details]
License BSD-3-Clause
Copyright (c) 2025 Mihai Giurgeanu
Author Mihai Giurgeanu
Maintainer mihai.giurgeanu@gmail.com
Category Git, Development
Home page https://github.com/mihaigiurgeanu/pr-tools
Bug tracker https://github.com/mihaigiurgeanu/pr-tools/issues
Source repo head: git clone https://github.com/mihaigiurgeanu/pr-tools.git
this: git clone https://github.com/mihaigiurgeanu/pr-tools.git(tag 0.1.0.0)
Uploaded by mihaigiurgeanu at 2025-07-31T09:42:43Z
Distributions
Executables pr-init, pr-fix, pr-view, pr-review, pr-merge, pr-track, pr-send, pr-snapshot
Downloads 3 total (3 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2025-07-31 [all 2 reports]

Readme for pr-tools-0.1.0.0

[back to package description]

PR Tools

A set of command-line tools for managing descentralized git pull requests and code review workflows. These tools help with creating PR snapshots, sending notifications to Slack, tracking approvals, merging PRs, reviewing changes, and viewing annotated diffs.

Please read the motivation for a more in-depth info about the purpose of these tools.

Features

  • pr-snapshot: Generate a Markdown snapshot of the PR including commits and diff summary.
  • pr-send: Send the PR snapshot to a Slack channel for review.
  • pr-track: Track PR approvals, status, and commit history.
  • pr-merge: Merge approved PRs with various strategies and update changelog.
  • pr-review: Interactive code review tool with comment management.
  • pr-view: View annotated diffs with review comments.
  • pr-fix: Fix comments received in a review.
  • pr-init: Interactively generate configuration file for pr-tools.

Installation

This project is built with Haskell and Cabal. To install:

  1. Ensure you have GHC and Cabal installed. Use GHCup for easy installation.
    • For Windows, you can use the Haskell Platform.
    • For macOS, you can install GHC and Cabal via Homebrew:
      brew install ghc cabal-install
      
  2. Clone the repository:
    git clone <repository-url>
    cd pr-tools
    
  3. Build and install the executables:
    cabal update
    cabal install
    

This will install the binaries in ~/.cabal/bin (or equivalent). Add this directory to your PATH if necessary.

How to upgrade from source

Update the source tree and reinstall:

cd pr-tools
git checkout master && git pull && cabal install --overwrite-policy=always

Configuration

Slack Configurations

PR Tools supports two Slack integration methods: Incoming Webhooks for simple text messages and Slack API Tokens for advanced features like file attachments. Webhooks are easier to set up and sufficient for basic notifications, while API Tokens enable uploading detailed content as files, improving readability for long messages (e.g., reviews or snapshots). If both are configured, the tool prioritizes API Tokens for commands that benefit from attachments; otherwise, it falls back to webhooks.

Webhook Configuration

Webhooks allow posting plain text messages to a Slack channel. This is ideal for short notifications but may truncate or clutter long content.

To obtain a webhook:

  1. Go to Slack Apps and create a new app.
  2. Enable "Incoming Webhooks" under "Add features & functionality".
  3. Activate webhooks and add one to a channel, copying the generated URL (starts with https://hooks.slack.com/services/).

Add to your .pr-tools.yaml:

slack-webhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

If not set, commands like pr-send will fail, and others (e.g., pr-merge) will skip notifications.

Slack API Token Configuration

API Tokens enable file attachments, allowing detailed messages (e.g., from pr-review send, pr-fix send, pr-send) to be uploaded as .md files with a short summary message. This requires a bot token with files:write scope.

To obtain a token:

  1. Go to Slack Apps and create a new app.
  2. Under "Add features & functionality", select "Bots" and create a bot user.
  3. Under "OAuth & Permissions", add the files:write scope (and optionally chat:write for messages).
  4. Install the app to your workspace, granting permissions.
  5. Copy the "Bot User OAuth Token" (starts with xoxb-).
  6. Find the channel ID: In Slack, right-click the channel, select "View channel details", and copy the ID (starts with C or G).
  7. Invite the pr-tools bot to the channel:
    /invite @pr-tools
    

Add to your .pr-tools.yaml:

slack-token: "xoxb-your-bot-token"
slack-channel: "C0123456789"  # Channel ID

Base Branch and Slack Configuration

Use pr-init or manually create a .pr-tools.yaml file in the project root with:

base-branch: main  # or your default base branch
slack-webhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"  # optional
slack-token: "xoxb-your-bot-token"  # optional for attachments
slack-channel: "C0123456789"  # required if using token

To avoid committing temporary files generated by pr-tools, add the following to your .gitignore file:

.pr-drafts/
.pr-reviews/
.pr-fixes/
.pr-state.yaml
.pr-tools.yaml  # Optional, if you don't want to commit the config

Usage

pr-snapshot

Generate a Markdown snapshot of the PR including commits and diff summary. The snapshot is saved in .pr-drafts/.md. If no message is provided, it opens an editor to enter the description.

pr-snapshot [BRANCH] [--base-branch BASE] [--message MESSAGE]
  • BRANCH: The feature branch (default: current branch).
  • --base-branch BASE: Override the configured base branch.
  • --message MESSAGE, -m MESSAGE: Provide the PR description directly without opening an editor.

pr-send

Send the PR snapshot to a Slack channel for review. Requires slack-webhook configured.

pr-send [BRANCH]
  • BRANCH: The feature branch (default: current branch).

pr-track

Track PR approvals and status.

Subcommands:

pr-track approve [BRANCH] --by NAME
pr-track status [BRANCH]
pr-track record [BRANCH]
pr-track update [BRANCH]
pr-track list
  • approve [BRANCH] --by NAME: Approve the PR by the given name. BRANCH defaults to current.
  • status [BRANCH]: Get the status, approvals, and merge status for the PR. Checks if commits are merged into the base branch. BRANCH defaults to current.
  • record [BRANCH]: Record or update the commit snapshot for the PR. Synonyms: update, u, r, rec. BRANCH defaults to current.
  • list: List all tracked PRs with status and approval counts.

pr-merge

Merge approved PRs with various strategies and update changelog. Optionally sends notification to Slack.

pr-merge [BRANCH] [--strategy {fast-forward|squash|rebase}] [--base-branch BASE]
  • BRANCH: The feature branch (default: current).
  • --strategy STRATEGY: Merge strategy (default: fast-forward).
  • --base-branch BASE: Override the configured base branch.

pr-review

Interactive code review tool with comment management.

Subcommands:

pr-review start [--base-branch BASE]
pr-review next
pr-review previous
pr-review open
pr-review files
pr-review changes
pr-review comment --file FILE --line LINE --text "COMMENT"
pr-review resolve --id ID
pr-review end
pr-review list
pr-review send
pr-review comments [--with-context]
  • start [--base-branch BASE]: Start or resume a review session. --base-branch overrides configured base.
  • next: Move to the next file and open in editor for commenting.
  • previous: Move to the previous file and open in editor.
  • open: Open the current file in editor for commenting.
  • files: List files with changes, indicating current.
  • changes: Show the git diff.
  • comment --file FILE --line LINE --text "COMMENT": Add a comment via CLI.
  • resolve --id ID: Mark a comment as resolved.
  • end: End the review session.
  • list: List all review sessions.
  • send: Send the review comments to Slack.
  • comments [--with-context]: List comments, optionally with code context.

pr-view

View annotated diff or comments.

Subcommands:

pr-view diff [BRANCH] [--base-branch BASE] [--full]
pr-view comments [BRANCH]
  • diff [BRANCH] [--base-branch BASE] [--full]: Show annotated diff with comments. --full shows complete files including unchanged areas. BRANCH defaults to current.
  • comments [BRANCH]: List all comments with context. BRANCH defaults to current.
  • --base-branch BASE: Override the configured base branch.

pr-fix

Manage fix sessions for review comments.

Subcommands:

pr-fix start
pr-fix comments [--with-context]
pr-fix files
pr-fix open
pr-fix next
pr-fix previous
pr-fix resolve --id ID --status STATUS [--answer "Explanation"]
pr-fix end
pr-fix send
  • start: Start a fix session by pasting review comments into an editor.
  • comments [--with-context]: Display comments, optionally with context.
  • files: List files with comments, indicating current.
  • open: Open current file with comments inserted for editing and updating status/answers.
  • next: Move to next file and open.
  • previous: Move to previous file and open.
  • resolve --id ID --status STATUS [--answer "EXPLANATION"]: Update comment status (e.g., solved, not-solved, will-not-solve) and optional answer via CLI.
  • end: End the fix session, requires changes to be committed.
  • send: Send fix summary to Slack.

pr-init

Interactively generate or update configuration file (.pr-tools.yaml) for pr-tools, prompting for base-branch, optional slack-webhook, slack-token, slack-channel, and stale-days (with current values as defaults if updating). Also updates .gitignore with recommended entries.

pr-init

No additional flags.

Sample Workflow

  1. Create a Feature Branch: Developer creates a branch, makes changes, and commits.
  2. Generate Snapshot: Run pr-snapshot to create a Markdown description of the PR.
  3. Send to Slack: Run pr-send to notify the team via Slack.
  4. Track Approvals: Team members approve using pr-track approve <branch> or Slack reactions.
  5. Conduct Review: Reviewer runs pr-review start, navigates files with next/open, adds comments, then pr-review send to send compact review to Slack.
  6. Fix Comments: Developer runs pr-fix start, pastes the Slack review message, navigates with pr-fix next/open to edit files and mark comments (solved/not-solved/will-not-solve), adds answers, or use pr-fix resolve for CLI updates, then pr-fix end to commit changes, and pr-fix send to report back via Slack.
  7. View Annotated Diff: Anyone can run pr-view <branch> to see changes with comments (use --full for full files or pr-view comments for comment list).
  8. Merge PR: Once approved, run pr-merge <branch> to merge and update changelog.

This workflow enables collaborative reviews without committing review files to the repo, using Slack for communication.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the BSD-3-Clause License.