## Project Overview

Patchpal is an AI-assisted cherry-picking and merge conflict resolution tool written in Rust.
It helps developers backport commits between software versions, particularly useful for
maintaining stable releases and handling complex merge scenarios.

## Building and testing

- `cargo build --release` builds with LTO and is slow to finish
- `cargo build` is suitable to ensure your changes compile
- binaries built without `--release` are unsuitable for testing due to their poor performance
- `./tests/run.sh` runs integration tests (TAP format).
  Before running tests, you must build with `--release`.

## Code structure

- **`src/common/`**: Core algorithms and shared functionality
- **`src/ui/`**: UI logic and state management, independent on the actual UI frontend
- **`src/bin/`**: 
  - `patchpal-gtk/`: GTK4-based GUI application
  - `patchpal-cli/`: CLI interface
  - `extractor/`: Utility for extracting samples for model fine-tuning
  - `benchmark/`: Performance tests

## Development patterns

- Maintain clean separation between algorithms, UI logic and UI presentation layers.
- There are three distinct modes: backporting, resolving of merge conflicts and working as
  a git mergetool.
- Performance is important.
- Before adding a new method, look at the existing methods to see whether some of them
  can be abstracted.

## Performance considerations

- Do not clone needlessly.
- Do not copy large memory chunks unless there's no other way.
- Do not block the GUI.

## Power user friendliness

- The GTK4 frontend must maintain efficient and complete operation using the keyboard.
- When adding a new keyboard shortcut, update `src/bin/patchpal-gtk/keyboard_help.rs`.
- Do not bloat the UI. It must be self-evident and discoverable but not over-descriptive in
  a way that would annoy experienced users.

## Coding style

- When importing modules, sort them alphabetically in the `use` clauses. Sort the `use`
  clauses alphabetically, too.
- Do not use nested braces in `use` clauses (e.g., avoid
  `use gtk::{glib, gdk::{Key, ModifierType}};`).
  Use separate imports or flatten the structure instead.
- Do not comment obvious constructs.
- Do not remove existing comments.
- Prefer functional programming whenever practical.
- Do not use multiple consecutive empty lines.
- Maximum line length is 94 characters.
- Do not split statements that fit within the maximum line length to multiple lines.
- Do not split existing lines that you're not modiyfing.
- Use short but descriptive variable names. Do not use single character variable names except
  for `i` in iteration over integer ranges. Do not use abbreviations such as `lv` for
  `list_view`. But you can use such abbreviated or single character arguments in very short
  closures.
- Do not introduce compiler warnings.

## Commit message style

- When committing, add `Assisted-by: <your designator here>` just before my `Signed-off-by`
  line. Do not use `Co-authored-by` or similar tags. Do not put any other "Generated with" or
  similar lines to the commit message; the Assisted-by tag is enough to convey the information.
- Do not use emoji in the commit message. Limit yourself to ASCII.
- Focus on why you did the change, not on what the code does.
- Be brief.
