
Show HN: Gitorials – Tutorials as Git Repos - gw
https://gitorials.com/
======
z1mm32m4n
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](https://github.com/jez/vim-as-an-
ide) (how to configure Vim & use plugins)

\-
[https://scottylabs.org/wdw/frontend/lab/](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.

~~~
acemarke
I've been trying to something sort of along this line with my "Practical
Redux" tutorial series ( [http://blog.isquaredsoftware.com/series/practical-
redux](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.

------
kovek
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.

------
colemannugent
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.

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

------
hergin
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.

------
kotojo
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.

------
ben_jones
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.

------
jtwaleson
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](https://github.com/jtwaleson/HelloGit)

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

[http://github.com/alexspeller/kondiment](http://github.com/alexspeller/kondiment)

------
superasn
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)

------
artpar
Slightly relevant: [https://artpar.github.io/](https://artpar.github.io/)

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

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

------
coldtea
So "Gitorials" comes from "git tutorials"?

How would they name a CLI tutorials site?

~~~
sctb
Could you please not?

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

------
nurettin
Ön u ut fddddd xd aa

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

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

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

