5 ms·

Show HN: Gitorials – Tutorials as Git Repos

147 points by gw 9y ago

hkon 9y ago
I'm sorry, I did not understood how it worked. Blogposts 4 ever
kovek 9y ago
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.
coldtea 9y ago
So "Gitorials" comes from "git tutorials"? How would they name a CLI tutorials site?
- sctb 9y ago
  Could you please not?
  - coldtea 9y ago
    I'd try not to next time, but now it's obviously too late. But wouldn't a down-vote suffice?
  - benbristow 9y ago
    Could you please lighten up a little?
kotojo 9y ago
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.
z1mm32m4n 9y ago
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 9y ago
  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.
- gw 9y ago
  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/ 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 https://github.com/copy/v86
artpar 9y ago
Slightly relevant: https://artpar.github.io/ https://artpar.github.io/ This shows the commit as "being written in front of you"
hergin 9y ago
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.
spellboots 9y ago
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
colemannugent 9y ago
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 9y ago
  Hows that an improvement over downloading the days lab from a web server?
nurettin 9y ago
Ön u ut fddddd xd aa
- nurettin 9y ago
  Sorry HN, 2 year old keeps on posting. I will remove all HN apps.
  - dang 9y ago
    If only the two-year-olds were the worst of our contributors.
jtwaleson 9y ago
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
Exuma 9y ago
Honestly I thought the name was "glitoris"... I can't say it's not a bad name.
ben_jones 9y ago
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.
superasn 9y ago
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)

147 points by gw 9y ago

hkon 9y ago

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

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.

coldtea 9y ago

So "Gitorials" comes from "git tutorials"? How would they name a CLI tutorials site?

sctb 9y ago
Could you please not?
- coldtea 9y ago
  I'd try not to next time, but now it's obviously too late. But wouldn't a down-vote suffice?
- benbristow 9y ago
  Could you please lighten up a little?

kotojo 9y ago

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.

z1mm32m4n 9y ago

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 9y ago
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.
gw 9y ago
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/ 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 https://github.com/copy/v86

artpar 9y ago

Slightly relevant: https://artpar.github.io/ https://artpar.github.io/ This shows the commit as "being written in front of you"

hergin 9y ago

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.

spellboots 9y ago

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

colemannugent 9y ago

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 9y ago
Hows that an improvement over downloading the days lab from a web server?

nurettin 9y ago

Ön u ut fddddd xd aa

nurettin 9y ago
Sorry HN, 2 year old keeps on posting. I will remove all HN apps.
- dang 9y ago
  If only the two-year-olds were the worst of our contributors.

jtwaleson 9y ago

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

Exuma 9y ago

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

ben_jones 9y ago

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.

superasn 9y ago

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)