Show HN: Gitorials – Tutorials as Git Repos | Hacker News Reader

Show HN: Gitorials – Tutorials as Git Repos

gitorials.com

147 pointsgw25 comments

I've tried this idea out before (on three occasions, with different approaches, but the same name :P).

I think this approach has a lot of promise. Compared to normal blog posts, being able to see the diff and the entire snapshot of the code at this step is luxurious.

The biggest problem I always ran into was that it's brittle. Made a mistake creating the gitorial on step 3 of 10? You have to rebase, which throws off all your commit hashes down the road. You can get around this with automatically creating tags for the steps, but the fact of the matter is, it's brittle.

I also don't like that it's a CLI only tool. When I'm reading tutorials online, I don't want to have to leave my browser—on mobile, I can't leave my browser!

For the purposes of prototyping, these are the two attempts I've had at creating a similar experience in the past:

- https://github.com/jez/vim-as-an-ide (how to configure Vim & use plugins)

- https://scottylabs.org/wdw/frontend/lab/ (intro to JavaScript by making a simple board game)

Neither my two solutions nor the OP's solutions are perfect, but the idea in general holds a lot of promise.

I've been trying to something sort of along this line with my "Practical Redux" tutorial series ( http://blog.isquaredsoftware.com/series/practical-redux ), as well as other technical blog posts. I kind of fell into the pattern of writing the initial code for the next post, then going through it again as I write the blog post and cleaning up the commits to be more coherent. The post walks through the "final" commits step-by-step, links to each commit on Github, has code snippets for files in those commits that show either a diff or the entire file contents, and also links to those specific file versions as well. I've been manually copying and pasting commit hashes and links into the posts, which does take work, but it hasn't been worth trying to automate yet.

That is a valid point -- I had to get quite used to git rebase while making the initial gitorials =) If all you need to modify is the commit messages, this tool apparently is a nice option:

https://bokub.github.io/git-history-editor/

In the future, I'd like to extend the shell tool to have a nice "edit mode" that runs git rebase underneath. I haven't thought through how to deal with merge conflicts, though.

Being able to run the tutorials online would be ideal, but that will require a full-fledged OS to run the project. That could be done server-side with a sandboxed OS ($$$) or, intriguingly, perhaps it could be done entirely client-side using an in-browser Linux emulator:

https://github.com/copy/v86

It would be cool to make a tool for 'playing back' git repos like this. I could see it having media player style controls so you can jump anywhere in progress, step to the next or previous commit, etc. At each commit, you could have a rendering of the diff, along with interspersed annotations. Maybe there could be a format for annotations, so multiple people could submit annotations for the same repos (or subsets of repos), and you'd end up with different tutorials.

So, in order to make one of these tutorials, you feed the software the url to the repo, start/end commit hashes, and some JSON or whatever that contains your annotations—and it gives you back an interactive presentation of annotated diffs.

With a business like this it's more important to make it easy on the content providers than optimizing the user experience for consumers.

At some mass the algebra changes and it's all about making consumption seamless.

This is the right direction. I encourage the author of this to really think about the experience of making the tutorial for the next few months as the business grows.

I made one seven years ago. I used stgit to make jumping back and forth in history so much easier than using rebase.

https://github.com/bryanlarsen/agility-gitorial-patches

I think that this is a great idea!!

Following the commit tree allows you to easily modify the code without breaking it, and then quickly test out the results by running it while you're looking at the gitorial.

If need be, the learner can easily find the important pieces of code to fiddle with, because they are presented in the diffs for each commit.

I have though about a properly designed "code-demo" branch for learning about a project. I have never tried it, but I think that maintaining a branch where you show the development of the core of the logic would be interesting. I was thinking that you could have all logging statements kept in a separate branch that you can merge into this "code-demo" branch. This way, you can easily get rid of the logging statements when you're looking at this code-demo branch, for example.

So instead of running the code for your interactive tutorial in my very handy cross-platform graphical javascript sandbox I should clone a git repo and run a shell script that starts a binary? That's just asking for it.

With all that being said I do like the concept though. It could work in classrooms where students could just git clone the days lab and get started.

Hows that an improvement over downloading the days lab from a web server?

It would be more interesting for GUI based projects. For example a WPF or html/css application. Seeing how it evolves step by step would be nice. Of course I am assuming the repository has logical commits.

I like the idea, but I'm not really interested in learning java. I'll have to save this for later and see if it grows.

This could be a great Hugo theme. Rendering Github-flavored-markdown into a nicely presented tutorial page. Bonus points if you could somehow incorporate Git commits so tutorial-goers could diff their code to find typos etc. You wouldn't even need an external site with github pages doing the hosting out of the box.

I had the same idea a couple of years ago, but never created a business or a website for it. Here's the one tutorial I created this way (NodeJS + Express): https://github.com/jtwaleson/HelloGit

I made a similar tool if you want to output a nicely formatted HTML tutorial:

http://github.com/alexspeller/kondiment

It would be cool to have a Gitorial about using Gitorials.com. I get the idea of this project but don't really know where to start and how to do it (like make corrections, add links, etc)

Slightly relevant: https://artpar.github.io/

This shows the commit as "being written in front of you"

Honestly I thought the name was "glitoris"... I can't say it's not a bad name.

So "Gitorials" comes from "git tutorials"?

How would they name a CLI tutorials site?

Could you please not?

I'd try not to next time, but now it's obviously too late. But wouldn't a down-vote suffice?

Could you please lighten up a little?

Ön u ut fddddd xd aa

Sorry HN, 2 year old keeps on posting. I will remove all HN apps.

If only the two-year-olds were the worst of our contributors.

I'm sorry, I did not understood how it worked. Blogposts 4 ever

Reply on news.ycombinator.com