https://github.com/ickk/diffwita
proof of concept. Tutorialise git trees
https://github.com/ickk/diffwita
Last synced: about 1 month ago
JSON representation
proof of concept. Tutorialise git trees
- Host: GitHub
- URL: https://github.com/ickk/diffwita
- Owner: ickk
- Created: 2023-02-15T02:38:23.000Z (over 3 years ago)
- Default Branch: dev
- Last Pushed: 2023-02-16T21:31:43.000Z (over 3 years ago)
- Last Synced: 2025-01-08T18:45:30.963Z (over 1 year ago)
- Language: Rust
- Homepage:
- Size: 44.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
This is a proof of concept.
Diffwita
---
A (WIP) tool to turn a git tree into a tutorial. It's like a simple form of
[*literate programming*](https://en.wikipedia.org/wiki/Literate_programming).
The way it works is you simply include markdown in your commit messages that
describes the changes in that particular commit. Diffwita then turns it into a
lovely document.
***Why?***
- It's kind of silly.
- Lets tutorials include a single source of truth for both the text of a
tutorial and the project the tutorial is building.
- The audience can be sure that if they follow your tutorial, it will build
because you can't make a mistake or leave something out when the diff itself
constitutes the tutorial.
- Readers can browse the change-log and directly relate the change with the
relevant section of the tutorial since the commit message includes the
tutorial.
**To do:**
- automatically build a table of contents, linkify headings, separate into
multiple pages.
- create a markdown block that lets you specify where a particular file will
appear in the markdown.
- use libgit2 instead of calling out to the system's git install.
- probably should rewrite a bunch of it to take advantage of the templating
library I used instead of messing around so much with the markdown
processor.
- make links to commit SHAs actually resolve properly.
- syntax highlighting.
**Notes:**
- You almost certainly want to configure the repository with:
```sh
git config --local commit.cleanup scissors
```
which prevents git from removing your headings; `#` is a comment to git by
default, and gets removed from your commit messages.
- If you want to create a section in your document with only text but no code
changes, the command you need is:
```sh
git commit --allow-empty
```