james.maes
f3aff06227
Complete implementation of PENNY (Prose Engine for Narrative, Notes, and Yarns) as an Obsidian community plugin. Core modules: annotation parser, version assembler, chapter versioner, frontmatter manager, voice compliance checker, context assembler, prompt drafter, chapter migrator. Plugin shell: main plugin class, settings tab with 5 collapsible sections, 11 command palette commands, project init wizard, status bar widget, review note generator, activity logger. Documentation: README, 9 user guides (getting started, annotations, configuration, project structure, versioning, voice enforcement, git workflow, troubleshooting, API costs), test fixtures. Testing: 170 unit tests across 8 test files, all passing. Build: esbuild production bundle (30KB main.js). CI: GitHub Actions release workflow.
125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# Git Workflow
|
|
|
|
PENNY includes git integration for committing and pushing your writing progress. It generates descriptive commit messages based on what changed in your revision session.
|
|
|
|
## How Commit Messages Are Generated
|
|
|
|
When you run **PENNY: Commit progress**, PENNY:
|
|
|
|
1. Runs `git status` to find all changed files in the vault.
|
|
2. Categorizes the changes:
|
|
- New chapter versions
|
|
- Updated frontmatter
|
|
- New review notes
|
|
- Outline changes
|
|
- Character sheet edits
|
|
- Activity log entries
|
|
3. Generates a commit message summarizing the session.
|
|
|
|
### Example commit message:
|
|
|
|
```
|
|
docs(book-1): revise ch-05 v3, ch-07 v2
|
|
|
|
ch-05: processed 3 annotations (REWRITE, EXPAND, DIALOG), +450 words
|
|
ch-07: processed 1 annotation (TONE), voice compliance pass
|
|
```
|
|
|
|
The first line follows the format configured in settings (default: `docs({chapter}): PENNY v{version} - {tags}`). The body lists per-chapter details.
|
|
|
|
### Customizing the format:
|
|
|
|
Change the commit message template in Settings > PENNY > Commit Message Format.
|
|
|
|
Available placeholders:
|
|
|
|
| Placeholder | Value |
|
|
|-------------|-------|
|
|
| `{chapter}` | Chapter identifier (e.g., `ch-05`) |
|
|
| `{version}` | New version number |
|
|
| `{tags}` | Processed annotation tags |
|
|
| `{book}` | Book identifier (e.g., `book-1`) |
|
|
| `{words}` | Word count delta |
|
|
|
|
When multiple chapters are committed together, PENNY generates a summary message listing all chapters.
|
|
|
|
## Auto-Commit and Auto-Push
|
|
|
|
Two settings control automatic git behavior:
|
|
|
|
| Setting | Default | What it does |
|
|
|---------|---------|--------------|
|
|
| Auto-commit after processing | Off | Commits after PENNY finishes processing a chapter |
|
|
| Auto-push after commit | Off | Pushes to remote after committing |
|
|
|
|
**Recommendation:** Leave both off while you are learning PENNY. Once you trust the output, auto-commit is convenient. Auto-push is useful if you want an off-site backup of every revision.
|
|
|
|
## What Gets Staged
|
|
|
|
PENNY stages only files related to your novel project:
|
|
|
|
- New chapter versions (`ch-XX.vN.md`)
|
|
- Version manifests (`.version`)
|
|
- State files (`.state.json`)
|
|
- Review notes
|
|
- Activity logs
|
|
- Updated character sheets, outlines, or wiki entries (if modified)
|
|
|
|
PENNY does **not** stage:
|
|
|
|
- Plugin configuration (`.obsidian/` directory)
|
|
- Files outside the project folder
|
|
- Unrelated vault files
|
|
|
|
The staging uses `git add` with specific file paths, not `git add -A` or `git add .`.
|
|
|
|
## The Three Git Commands
|
|
|
|
### PENNY: Commit progress
|
|
|
|
Stages project files and commits with an auto-generated message. This is the primary git command.
|
|
|
|
1. Finds changed files.
|
|
2. Stages relevant files.
|
|
3. Generates commit message.
|
|
4. Commits.
|
|
5. Shows a notice with the commit summary.
|
|
|
|
### PENNY: Push
|
|
|
|
Pushes committed changes to the remote. Equivalent to `git push`.
|
|
|
|
If no remote is configured, PENNY shows an error notice: "No remote configured. Run 'git remote add origin <url>' in your terminal."
|
|
|
|
### PENNY: Commit and push
|
|
|
|
Runs commit followed by push in one action. Convenience command for when you want to back up immediately.
|
|
|
|
## Safety
|
|
|
|
PENNY's git operations follow strict safety rules:
|
|
|
|
- **No force-push.** PENNY never runs `git push --force` or `git push --force-with-lease`.
|
|
- **No rebase.** PENNY never runs `git rebase`.
|
|
- **No destructive operations.** PENNY only uses `git add`, `git commit`, `git push`, `git status`, and `git log`.
|
|
- **No branch manipulation.** PENNY does not create, delete, or switch branches.
|
|
- **Staging is specific.** PENNY stages individual files by path, not the entire working directory.
|
|
|
|
If a push fails (e.g., due to remote changes), PENNY shows the error and lets you resolve it manually. It does not attempt to pull, merge, or force-push.
|
|
|
|
## Working Without Git
|
|
|
|
Git integration is entirely optional. If your vault is not a git repository, PENNY's git commands show a notice: "Not a git repository. Git features are disabled."
|
|
|
|
All other PENNY features (annotations, processing, versioning, reviews) work without git. The chapter versioning system is independent of git -- it uses numbered version files, not git history.
|
|
|
|
If you want version history without git, PENNY's built-in versioning provides it. If you want off-site backup, consider using Obsidian Sync, a cloud-synced folder, or initializing a git repo.
|
|
|
|
## Tips
|
|
|
|
**Commit after each revision pass.** This gives you git-level undo in addition to PENNY's version files. If something goes wrong, you can `git checkout` the previous state.
|
|
|
|
**Use meaningful branches.** If you are working on a major revision of a chapter (e.g., restructuring act 2), consider creating a git branch first: `git checkout -b revise-act-2`. This keeps your main branch clean while you experiment.
|
|
|
|
**Review before pushing.** Even with auto-commit enabled, leaving auto-push off gives you a chance to review the commit before it goes to the remote. Run `git log --oneline -5` in a terminal to see recent commits before pushing.
|