Not everything you want to share deserves a whole repository. A handy shell script, a config file that finally worked, a SQL query you keep reusing, or a few notes for a colleague are too small for a project of their own, but too useful to lose in a chat message.
GitHub Gists are made for exactly this: quick, shareable snippets with syntax highlighting, a link you can send to anyone, and a full version history behind them. Each gist is actually a tiny Git repository, so you can clone it, edit it and push changes.
At the other end of the scale, projects need documentation: installation guides, architecture notes, FAQs. A repository's built-in wiki gives you a set of linked Markdown pages for that, editable in the browser. In this lesson you'll create gists, use them from the terminal, set up a wiki, and learn when documentation is better kept in a docs folder or published with GitHub Pages instead.
Creating gists
Go to gist.github.com (or the + menu, then New gist):
- Give a short description.
- Enter a file name with an extension, such as
backup.shorquery.sql, so GitHub highlights the right language. - Paste the content. Add more files with Add file if they belong together.
- Choose Create secret gist or Create public gist.
Every edit creates a new revision, viewable under the Revisions tab, and people can star, fork and comment on gists, much like repositories. Markdown files (.md) are rendered nicely, which makes gists good for short how-to notes too.
Public or secret?
| Public gist | Secret gist | |
|---|---|---|
| Listed on your profile | Yes | No |
| Found in GitHub search | Yes | No |
| Viewable with the link | Yes | Yes |
"Secret" means unlisted, not private: anyone who has the link can read it. Never put passwords, API keys or personal data in any gist. For truly private sharing, use a private repository. You can turn a secret gist into a public one later, but not the other way round.
Gists from the terminal
The GitHub CLI works with gists:
gh gist create backup.sh --desc "Nightly backup script"
gh gist list
gh gist view <id>
gh gist edit <id>Because each gist is a Git repository, you can also git clone its URL, commit changes and push. Paste a gist's URL into many blogs, forums and documentation tools and it's shown inline, and the Embed option on the gist page gives you a script tag for your own site.
Wikis
Every repository can have a wiki: switch it on under Settings, Features, Wikis, then open the Wiki tab.
- Each page is a Markdown file; Home is the start page.
- Link pages with
[[Page Name]]or normal Markdown links. - A page called _Sidebar becomes a navigation menu on every page, and _Footer a footer.
- The wiki is a separate Git repository, cloneable at the repository's address with
.wiki.giton the end, so you can edit pages in your own editor and push.
By default, anyone with write access can edit. For public projects you can restrict editing to collaborators in the settings.
GitHub Gists Syntax
Gists and wikis
gh gist create file.sh --desc "Description" # secret by default
gh gist create notes.md --public
gh gist list
git clone https://gist.github.com/<id>.git
git clone https://github.com/<owner>/<repo>.wiki.gitWiki links: [[Installation]] [[Install guide|Installation]]
Special pages: Home, _Sidebar, _FooterGitHub Gists Summary
- Gists share small snippets with highlighting, revisions, stars, forks and comments.
- Secret gists are unlisted, not private: anyone with the link can view them.
- gh gist create and git clone let you manage gists from the terminal.
- A repository wiki is a set of linked Markdown pages, with _Sidebar for navigation.
- Docs that must match the code usually belong in a docs folder, reviewed in pull requests.
GitHub Gists Examples
Each example shows the code, the output it produces and what each part does.
Sharing a snippet from the terminal
gh gist create clean-downloads.sh --desc "Delete downloads older than 30 days"
gh gist list --limit 2- Creating gist clean-downloads.sh
✓ Created secret gist clean-downloads.sh
https://gist.github.com/samlee/3f8a1c2d9e7b4a6f5c0d1e2f3a4b5c6d
3f8a1c2d9e7b4a6f5c0d1e2f3a4b5c6d Delete downloads older than 30 days 1 file secret about 1 minute ago
a71b2c3d4e5f60718293a4b5c6d7e8f9 Useful git aliases 1 file public about 3 days agoLine-by-line explanation
- Line 1Creates a secret gist from a local file, with a description. Add --public to list it on your profile.
- Line 2List your most recent gists. Each has an id, which is also part of its URL.
A wiki with a sidebar
<!-- _Sidebar.md -->
**Recipe Box docs**
- [[Home]]
- [[Installation]]
- [[Configuration]]
- [[Deploying|Deploying to GitHub Pages]]
- [[FAQ]]Every wiki page now shows a menu on the right:
Recipe Box docs
• Home
• Installation
• Configuration
• Deploying
• FAQLine-by-line explanation
- Line 1A page named _Sidebar is shown on every other page.
- Lines 4 to 8[[Page]] links to a wiki page by title.
- Line 7[[Text|Page Name]] shows different link text from the page's title.
Editing a wiki locally
git clone https://github.com/samlee/recipe-box.wiki.git
cd recipe-box.wiki
ls
echo "## Common problems" >> FAQ.md
git commit -am "Add common problems section to FAQ"
git pushCloning into 'recipe-box.wiki'...
Configuration.md FAQ.md Home.md Installation.md _Sidebar.md
[master 6b2d9e4] Add common problems section to FAQ
1 file changed, 1 insertion(+)
To https://github.com/samlee/recipe-box.wiki.git
1c0b9a8..6b2d9e4 master -> masterLine-by-line explanation
- Line 1The wiki is its own repository: the project's address with .wiki.git on the end.
- Line 3Each page is a Markdown file named after its title.
- Lines 5 to 6Commit and push like any repository; the Wiki tab updates straight away. Wikis often still use master as their branch name.
Common GitHub Gists Mistakes
Secrets in a "secret" gist
Secret gist containing: DATABASE_URL=postgres://admin:hunter2@db.example.comShare the code with placeholders: DATABASE_URL=postgres://user:password@host/db
Keep real values in a password manager or environment variablesAnyone with the link can read a secret gist, and links get shared.
No file extension in a gist
Filename: backup -> shown as plain textFilename: backup.sh -> highlighted as a shell scriptSetup steps only in the wiki
Install steps in the wiki; code changes the steps; nobody updates the wikiInstall steps in README.md or docs/, updated in the same pull request as the codeGitHub Gists in Real Projects
Gists and wikis in practice
Developers keep personal libraries of useful snippets in gists, from editor settings to one-off scripts, and share them in answers and blog posts. Many open-source projects use their wiki for community-maintained guides, FAQs and roadmaps, while keeping official, versioned documentation in the repository and publishing it with a docs site.
GitHub Gists FAQ
Can a gist contain more than one file?
Yes. Use the button to add another file when you create or edit a gist, and each file gets its own name and syntax highlighting. Gists can't contain folders, though, so for anything with a folder structure use a repository.
Can I see older versions of a gist?
Yes. Every save creates a new commit, and the gist's Revisions tab shows each change as a diff. Because a gist is a Git repository, you can also clone it and run git log.
Can I fork or star someone else's gist?
Yes. Starring saves it to your list of starred gists so you can find it later. Forking creates your own copy that you can edit, while the original stays linked from your copy.
Who can edit a repository's wiki?
By default, people with write access to the repository. On a public repository the owner can choose whether only collaborators may edit, or anyone with a GitHub account. Restricting editing to collaborators is the safer choice for most projects.
How do I find all my gists?
Go to gist.github.com/your-username to see your gists, or use the Your gists link in the profile menu. Secret gists appear in the list only when you're signed in, and you can search your gists from the same page.
GitHub Gists Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Complete the command that creates a public gist.
gh gist create notes.md --What is a secret gist?
Why give a gist file an extension like .sql?
Which wiki page appears as a menu on every page?
Where should installation steps that change with the code usually live?
GitHub Gists Quiz
5 questions to check what you learned.
What is a gist?
- A type of branch
- A pull request comment
- A GitHub Action
- A shareable snippet or small set of files with its own history
How do you clone a repository's wiki?
- git clone the repository URL with .wiki.git on the end
- git clone <repo>/wiki
- gh wiki clone
- Wikis can't be cloned
How do you link to a wiki page titled Installation?
- {{Installation}}
- <Installation>
- [[Installation]]
- #Installation
Can a public gist be made secret later?
- Yes, any time
- Only by GitHub support
- Only within an hour
- No, but a secret gist can be made public
What's one drawback of wikis compared with a docs folder?
- Wikis can't use Markdown
- Wiki edits aren't reviewed in pull requests or tied to code versions
- Wikis are always private
- Wikis can't have links