Dev Snippets

Ship a tidy repository

The three files people forget until it's awkward

Every public repository eventually needs the same three pieces of housekeeping: a .gitignore before the first accidental node_modules commit, a LICENSE before the first person asks "can I use this?", and README badges once the project is worth presenting. Each tab here generates one of them. Pick your stacks as chips and the ignore rules merge into one deduplicated file; choose a license and type your name and year to get the full legal text; set your GitHub owner and repo to build shields.io badges with a live preview of exactly how they'll render.

Choosing a license without a law degree

For most open-source work the decision tree is short. MIT is the default permissive license: anyone may use, modify and sell, as long as your copyright notice survives. Apache-2.0 is MIT's spirit plus an explicit patent grant, which larger companies appreciate when evaluating dependencies. BSD and ISC are close MIT relatives with slightly different phrasing, and the Unlicense waives copyright entirely for public-domain dedication. The one real mistake is shipping no license at all — legally, "no license" means all rights reserved, and cautious teams simply won't touch the code.

A .gitignore that matches how you actually work

Good ignore files layer three concerns, and the chip presets mirror that: your language's build artifacts (like dist/ or __pycache__/), your operating system's noise (.DS_Store, Thumbs.db), and your editor's local settings. Combining presets here beats copying a giant kitchen-sink file from another repo — you get rules you can read, and you can regenerate when the stack changes. Commit it as the repository's first file and secrets-in-history problems get much rarer.

Step-by-step: the first ten minutes of a new repository

Start on the .gitignore tab. Four chips are pre-selected — Node, macOS, VS Code and Env & secrets — so click them off if they don't apply and click on the ones that do: languages (Python, Java, Go, Rust, PHP, Ruby, .NET, C/C++, Swift, Unity), operating systems (Windows, Linux), editors (JetBrains) and the catch-all Logs & temp. The preview regenerates on every click; hit Download to get a file literally named .gitignore, or Copy and paste into your editor. Switch to License, choose from the dropdown, correct the year and replace "Your Name" with the copyright holder — a person or a company, exactly as you want it to appear — then download as LICENSE. Finally, open README badges, type your GitHub owner and repository, choose a style (flat, flat-square, for-the-badge or plastic), toggle the badges you want and copy the Markdown block to the top of your README. The live preview fetches the real images, so what you see is what GitHub will render.

Common mistakes and how to avoid them

• Ignoring the lockfile. The Rust preset ignores Cargo.lock, which is correct for libraries but wrong for binaries; delete that line for an application. For Node, never ignore package-lock.json — reproducible installs depend on it.
• Committing .env before adding the rule. Once a secret is in history, ignoring the file does not remove it; rotate the credential and rewrite history if the repo is public. Keep the Env & secrets preset on by default — it also allows .env.example through so teammates can see the expected variables.
• Picking Apache-2.0 and pasting only the header. The generated text is the standard boilerplate; the full license belongs in the LICENSE file and the short notice in source headers. The tool's output says so, and GitHub's license detection needs the full text to label the repo.
• Badges pointing at the wrong package. The npm version and downloads badges use the repository name as the package name. If your package is scoped or named differently, edit that segment of the shields.io URL after copying.
• A wall of badges. Three or four meaningful ones (license, version, build, PRs welcome) communicate; twelve communicate nothing. Turn off what you won't maintain.

How README badges work under the hood

Every badge is just an image URL on img.shields.io, optionally wrapped in a Markdown link. Path-based endpoints such as /github/license/owner/repo, /github/stars/owner/repo, /npm/v/name and /github/actions/workflow/status/... query the upstream service when the image is requested and render an SVG with the current value — which is why the badge updates without touching your README. Static badges use the /badge/label-message-color pattern, where spaces are encoded as %20 and dashes as --; the "PRs welcome" and "Made with TS" chips are built this way. The ?style= query parameter changes only the rendering: flat and flat-square are compact, for-the-badge is tall and uppercase, plastic is the original glossy look. Because GitHub proxies README images through its camo service, badges can lag a few minutes behind reality; that is caching, not a broken URL.

Further reading

Badges are SVG and READMEs often embed screenshots, so our guides on SVG optimization and minifying versus beautifying source files are natural next reads — or browse all guides.

Frequently asked questions