Skip to content

docs: document execute, interactive editor, templates, and webhook features#27

Merged
vitali87 merged 1 commit intomainfrom
docs/readme-update-all-features
Mar 24, 2026
Merged

docs: document execute, interactive editor, templates, and webhook features#27
vitali87 merged 1 commit intomainfrom
docs/readme-update-all-features

Conversation

@vitali87
Copy link
Copy Markdown
Owner

Summary

  • Document execute command for running saved dry-run plans
  • Document interactive plan editor (move, show, plan, done, abort)
  • Document custom PR body templates via .pr-split/template.md
  • Document --notify webhook flag for merge notifications
  • Add PR_SPLIT_WEBHOOK_URL to configuration table
  • Update "What it does" to mention interactive editor and dry-run/execute workflow

Test plan

  • README renders correctly
  • All 308 tests pass

@gemini-code-assist
Copy link
Copy Markdown

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the pr-split documentation by introducing new sections for recently added features and clarifying existing descriptions. The updates aim to provide users with a more complete and accurate guide on how to leverage advanced functionalities like webhook notifications, interactive plan editing, and custom PR templates, thereby improving the overall user experience and understanding of the tool's capabilities.

Highlights

  • New Feature Documentation: Added comprehensive documentation for the --notify webhook flag, the execute command for running saved dry-run plans, and the interactive plan editor, including its various commands.
  • Custom PR Body Templates: Introduced documentation for creating custom PR body templates using .pr-split/template.md and listed the available placeholders for dynamic content.
  • Configuration Update: Included PR_SPLIT_WEBHOOK_URL in the configuration table, detailing its purpose for merge notifications.
  • Workflow Clarification: Updated the 'What it does' section to reflect the new interactive editor and the dry-run/execute workflow, providing a clearer understanding of the tool's capabilities.
  • Command Description Refinement: Refined the description of the pr-split clean command to accurately state that it removes the plan file, rather than the entire .pr-split directory.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces documentation for the execute command, interactive plan editor, custom PR body templates, and the --notify webhook flag. It also updates the configuration table and the 'What it does' section in README.md to reflect these new features.

@greptile-apps
Copy link
Copy Markdown

greptile-apps bot commented Mar 24, 2026

Greptile Summary

This PR is a documentation-only update to README.md that documents four features already implemented in cli.py: the execute command, the interactive plan editor, custom PR body templates via .pr-split/template.md, and the --notify webhook flag for merge notifications.

All documented behaviours were verified against the source:

  • execute accurately describes using saved raw_diff and merge_base_sha from a dry-run plan.
  • Template placeholders ({description}, {files}, {added}, {removed}, {loc}, {dependencies}, {dag}, {id}, {title}) exactly match the template_vars dict in _build_pr_body.
  • PR_SPLIT_WEBHOOK_URL is correctly reflected as the envvar backing the --notify flag.
  • The clean description change from "removes the .pr-split directory" to "removes the plan file" is a documentation accuracy fix_cleanup_git_state only calls plan_path.unlink(), preserving .pr-split/template.md as expected.

Two minor style suggestions were left inline: clarifying that the interactive editor is scoped to split (not execute), and noting that hunk indices in the move command are 0-based.

Confidence Score: 5/5

  • Documentation-only change; all documented behaviours are accurate against the implementation and safe to merge.
  • Every new documentation claim was cross-checked against cli.py. No functional code was modified, and the two inline suggestions are purely cosmetic improvements to clarity.
  • No files require special attention.

Important Files Changed

Filename Overview
README.md Documentation-only update adding sections for execute, interactive plan editor, custom PR body templates, and --notify webhook. All documented behaviours are verified accurate against cli.py. Two minor style notes: the interactive editor section doesn't specify it's split-only, and hunk indices in the move example lack a 0-based clarification.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[pr-split split --dry-run] --> B[Plan displayed + Interactive Editor]
    B --> C{User action}
    C -->|done / Enter| D[Save plan to .pr-split/plan.json]
    C -->|abort| E[Cancel]
    D --> F[pr-split execute]
    F --> G[Load saved diff + merge base]
    G --> H[Display plan]
    H --> I{Confirm?}
    I -->|Yes| J[Create branches & commits]
    J --> K[Push & open PRs]
    K --> L[pr-split merge --notify URL]
    L --> M[Merge in DAG order]
    M --> N[POST results to webhook]
Loading
Prompt To Fix All With AI
This is a comment left during a code review.
Path: README.md
Line: 119

Comment:
**Interactive editor availability not scoped to `split`**

The "Interactive plan editing" section is placed after the `execute` command section with no indication it only applies to `split`. Since `execute` also shows a plan and prompts for confirmation (but does **not** invoke the interactive editor), readers may expect to edit the plan during `execute` and be confused when it doesn't happen.

Consider adding a clarifying note, for example:

```suggestion
After running `pr-split split`, the plan is displayed and an interactive editor lets you adjust the plan before confirming:
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: README.md
Line: 123

Comment:
**Hunk indices are 0-based — worth noting**

The code enforces `hunk_index >= 0` and displays indices as `0, 1, 2, …` in the `show` output (see `_show_group_detail`). The example `src/foo.py:2` refers to the third hunk. Documenting that indices are 0-based (as shown by `show <group>`) would prevent off-by-one errors for users.

```suggestion
edit> move src/foo.py:2 pr-1 pr-2   # move hunk at index 2 (0-based) from pr-1 to pr-2
```

How can I resolve this? If you propose a fix, please make it concise.

Reviews (1): Last reviewed commit: "docs: add execute, interactive editor, t..." | Re-trigger Greptile


### Interactive plan editing

After the plan is displayed, an interactive editor lets you adjust the plan before confirming:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Interactive editor availability not scoped to split

The "Interactive plan editing" section is placed after the execute command section with no indication it only applies to split. Since execute also shows a plan and prompts for confirmation (but does not invoke the interactive editor), readers may expect to edit the plan during execute and be confused when it doesn't happen.

Consider adding a clarifying note, for example:

Suggested change
After the plan is displayed, an interactive editor lets you adjust the plan before confirming:
After running `pr-split split`, the plan is displayed and an interactive editor lets you adjust the plan before confirming:
Prompt To Fix With AI
This is a comment left during a code review.
Path: README.md
Line: 119

Comment:
**Interactive editor availability not scoped to `split`**

The "Interactive plan editing" section is placed after the `execute` command section with no indication it only applies to `split`. Since `execute` also shows a plan and prompts for confirmation (but does **not** invoke the interactive editor), readers may expect to edit the plan during `execute` and be confused when it doesn't happen.

Consider adding a clarifying note, for example:

```suggestion
After running `pr-split split`, the plan is displayed and an interactive editor lets you adjust the plan before confirming:
```

How can I resolve this? If you propose a fix, please make it concise.


```
edit> show pr-1 # inspect a group's assignments
edit> move src/foo.py:2 pr-1 pr-2 # move a hunk between groups
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Hunk indices are 0-based — worth noting

The code enforces hunk_index >= 0 and displays indices as 0, 1, 2, … in the show output (see _show_group_detail). The example src/foo.py:2 refers to the third hunk. Documenting that indices are 0-based (as shown by show <group>) would prevent off-by-one errors for users.

Suggested change
edit> move src/foo.py:2 pr-1 pr-2 # move a hunk between groups
edit> move src/foo.py:2 pr-1 pr-2 # move hunk at index 2 (0-based) from pr-1 to pr-2
Prompt To Fix With AI
This is a comment left during a code review.
Path: README.md
Line: 123

Comment:
**Hunk indices are 0-based — worth noting**

The code enforces `hunk_index >= 0` and displays indices as `0, 1, 2, …` in the `show` output (see `_show_group_detail`). The example `src/foo.py:2` refers to the third hunk. Documenting that indices are 0-based (as shown by `show <group>`) would prevent off-by-one errors for users.

```suggestion
edit> move src/foo.py:2 pr-1 pr-2   # move hunk at index 2 (0-based) from pr-1 to pr-2
```

How can I resolve this? If you propose a fix, please make it concise.

@vitali87 vitali87 merged commit a1c917f into main Mar 24, 2026
4 checks passed
@vitali87 vitali87 deleted the docs/readme-update-all-features branch March 27, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant