Last week was my first week in a new job, which means my mind was in overdrive trying to pick up all the new concepts, best practices, and names that were being thrown my way. One of those concepts was that of a gist, which we used to share pieces of code with clients. I wanted to better understand the use of this tool, so I set out to learn…
What is a gist?
The first thing worth noting is that gist refers specifically to a GitHub feature. Bitbucket has a similar tool called snippets, which works in much the same way. With that said, a gist is a repository — a place to store your code that you can edit, update and share.
Like all repositories, gists can be forked and cloned. You can utilize GitHub version control to update your gists when you come up with a new idea, or revert back to what you were using before. They are unique in that, though they can be shared, only the creator of the gist can push new code. We cannot create branches in our gists either. In this way, they are essentially mini-repos: fewer features make them more lightweight and ideal for sharing small bits of code.
How do I create a gist?
Part of the beauty of the gist is just how easy they are to create. Simply log in to GitHub and click the plus sign in the upper-right corner of the page, like you were creating a new repo. You should notice the option to create a new gist:
Selecting that option will take you to a page where you can start working on your gist. Gists are generally small snippets of code or groupings of files that have a single purpose, so there’s a fair chance you won’t need advanced IDE extensions to get your work done. You can actually write your entire gist through GitHub. For example:
Once you’re happy with your code, scroll down and you’ll see the option to create a public or a secret gist.
Public or secret?
A public gist can be easily found and viewed by any visitors to https://gist.github.com/discover. Users can also search gists on the Discover page, so, if it wasn’t already obvious by the name, make sure not to put anything private in a public gist. A public gist cannot be converted to a secret gist, but it can be deleted in case you accidentally published something you’d like to keep to yourself.
Secret gists are harder to find, but not impossible to access. They are not listed on the Discover page and are not searchable, but they can be shared via URL. There are no security settings associated with their URL, so anyone who knows (or guesses) the path will be able to see them. If you are writing code that requires more security than that, GitHub suggests creating a private repository.
Is there any other way to create a gist?
I’m so glad you asked! We can also use the command line to create a gist, but first we’ll have to create a personal access token. On your GitHub account, head to Settings, then Developer Settings. You should then see Personal Access Tokens on the left:
Click on Generate new token, add a note to your token, and make sure to select gist under your scope:
You’ve got a token! Save it in a safe place because you won’t be able to find it again if you navigate away.
And now for the gist creation command! Don’t be intimidated by everything here, when we break it down, it’s actually pretty straightforward:
curl -X POST -d '{"public":true,"files":{"our-new-gist.txt":{"content":"We love the command line."}}}' -u mdiaz26:<PERSONAL ACCESS TOKEN HERE> https://api.github.com/gists- curl -X POST -d uses curl to make a post request with the -d flag indicating that data is to follow.
- The aforementioned data is a JSON string that includes a public boolean (true representing a public gist, false representing a secret gist) and files, which are the actual contents of the gist.
- First associated with files is the name of our one file: our-new-gist.txt. We then see the content of the file, which is a simple string stating “We love the command line.” If we were actually writing enough code to merit a gist, this part of our command would be a lot longer.
- Next we see the -u tag, representing the user. You can add your GitHub username (you see mine, mdiaz26, in our example) and then your personal access token.
- Finally we see the URL where we’re directing our gist. Once we run this command, we’ll have created a gist. Awesome!
If you run the command, you’ll see a long and potentially confusing response in the command line. We won’t go into all the detail here, but you can learn plenty from GitHub’s gists documentation. More importantly, if you head over to “Your gists” on GitHub, you’ll see the newly added gist!
Gists are a quick, easy way to share code on GitHub. Keep in mind that they lack thorough security protocols, so they aren’t useful in every instance. If you’d like to learn more about gists, check out these resources: