git-tutor: Generate programming tutorials from your git history

Git Tutor

Generate step-by-step markdown tutorials from your git history

Motivation

There is tons of tutorials on medium, personal blogs etc. Writing detailed and complete guide how to build things is kinda hard and people are lazy, so those tutorials sometimes incomplete, code examples don't work as-is (some "prerequisite" step was not included in tutorial), sometimes it walks you through only some peices of code and you can find the rest in repo. But you have no idea how the rest works.

Git is a perfect tool to build smth incrementally (commits). git-tutor walks through commit history and generates markdown, placing commit message first, content of a commit afterwards. Write markdown to your commit messages – have a nice tutorial later with single command

Some rules

• keep commits small and explain almost every line of code you're writing
• write markdown to your commit messages
• don't skip anything. Simple copy-paste should work to reproduce the result of your tutorial
• writing code is fun. Explaining how code works is even more of fun

Installation

npm i -g git-tutor

Usage

git-tutor . > README.md

Tips and tricks

I don't like commiting every line of code. What should I do to keep tutorial clean?

That's fine, I don't like it either. You can use git add -p and split your work into smaller chunks later

Git treats # as a comment by default

To be able to use this symbol and add headings you should reconfigure git cleanup symbol

git config commit.cleanup whitespace

How to use my favorite editor for writing markdown

Writing a lot of markdown is not really convenient in default git editor like vi , I prefer doing it in vscode as it allows to preview parsed markdown with all styling applied. To use vscode as git editor

• Install code command in $PATH ( Shift + CMD + P => Search for PATH )
• git config core.editor "code --wait"

Default commit template contains a lot of comments

To override default git template:

~/.gitmsg
git config commit.template ~/.gitmsg

Unsolved issues

• i18n (cherry-pick to new locale branch with translation?)
• updates to previous commits (rebase works, but not convenient)
• collobaration

LICENSE

WTFPL