40

I'm publishing a tutorial that includes a lot of code interspersed with documentation. I'm considering two ways of hosting the code:

  1. Separate git repository with code files and markdown files explaining the code
  2. Github gist containing both of these

Are there advantages of hosting in a gist v/s a repository? When would one prefer one of these over the other?

Anirudh Ramanathan
  • 46,179
  • 22
  • 132
  • 191
DivyaJyoti Rajdev
  • 734
  • 1
  • 9
  • 15

2 Answers2

52

Gist is a simple way to share snippets and pastes with others. Whereas Repo is simply a place where the history of your work is stored.

There is no good answer, it's personal preference. I make mine a conceptual distinction. If it's code designed to demonstrate a technique, teach a principle, or show off a solution it goes in a gist. Doesn't matter if it's one file or 30 files. If it's actual code intended to be run, used as is, or forked as boilerplate I put it in a proper repository.

Rahul Nigam
  • 535
  • 5
  • 6
2

If you use markdown files for your tutorial, now there is one important difference, even if you are only creating one file (and specially if it is a long one).

Since April 2021, .md files created in github repositories now include an automatic Table of Contents which greatly improves navegability. See this related SO answer for more info.

As far as I know, this automatic ToC does not exist in gist-created .md files, so I'd rather go for a repository in this case (OP mentioned "a lot of code interspersed with documentation").

abu
  • 422
  • 7
  • 14