Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lesnitsky/git-tutor
:octocat:+md=:heart: Awesome tutorials from your git log
https://github.com/lesnitsky/git-tutor
git markdown tutorial
Last synced: 2 days ago
JSON representation
:octocat:+md=:heart: Awesome tutorials from your git log
- Host: GitHub
- URL: https://github.com/lesnitsky/git-tutor
- Owner: lesnitsky
- License: other
- Created: 2017-10-16T21:14:52.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T01:17:05.000Z (almost 2 years ago)
- Last Synced: 2024-12-16T10:26:02.002Z (9 days ago)
- Topics: git, markdown, tutorial
- Language: JavaScript
- Homepage:
- Size: 56.6 KB
- Stars: 384
- Watchers: 14
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Git Tutor
[](https://lesnitsky.dev?utm_source=git-tutor)
[](https://travis-ci.com/R1ZZU/git-tutor)
[](https://twitter.com/lesnitsky_dev)
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 pieces 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
## Example tutorials
- [Tic Tac Toe](https://github.com/R1ZZU/tic-tac-toe)
## 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
```sh
npm i -g nodegit
npm i -g git-tutor
```
## Usage
```sh
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
```sh
git config commit.cleanup whitespace
```
### What if I want to leave general comment/explanation without any code
Git allows commits without any content
```sh
git commit --allow-empty
```
### 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 message template contains status in comment, how to remove it
You can pass `--no-status` flag to a `commit` command, this will strip those commented lines
```sh
git commit --no-status
```
You can also use your custom commit template:
- create empty file and place it somwhere in your file system (e.g. `~/.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](http://www.wtfpl.net/)
[](https://lesnitsky.dev?utm_source=git-tutor)
[](https://twitter.com/lesnitsky_dev)