[Research] Understand whether a .gira merge driver is useful

[StatPan]

Goal

Research what a Git merge driver would mean for Gira and whether Gira needs one for .gira files.

Context

The PyPI gira project appears to include a merge-driver idea for resolving conflicts in local .gira JSON state. Gira also uses .gira/config.yaml, but Gira's source of truth is GitHub execution state, not local project-management JSON.

Git supports custom merge drivers through .gitattributes and merge driver configuration. A merge driver can define how Git combines file changes during merges instead of using the default text merge behavior.

Reference:

• https://git-scm.com/docs/gitattributes
• https://pypi.org/project/gira/

Research Questions

• What exact conflict class would a Gira merge driver solve?
• Which .gira files, if any, are expected to be committed and edited by multiple branches?
• Would a merge driver be useful for config, cache, packet, export, or local backlog files?
• Should Gira instead avoid merge-sensitive committed local state?
• Is schema-aware merge worth the added installation and support complexity?

Candidate Outcomes

1. No merge driver needed; keep .gira committed files minimal.
2. Add documentation only: how to avoid conflicts and what not to commit.
3. Add a narrow merge driver for packet/backlog files if Gira later commits structured local state.
4. Add a generic JSON/YAML merge helper only if there is clear user pain.

Acceptance Criteria

• Explain custom Git merge drivers in Gira docs language.
• Inventory committed .gira files and their conflict risk.
• Decide whether merge-driver work is needed now, later, or not planned.
• If useful, propose the smallest supported file scope and installation UX.