A snippet library is only as good as its worst search. You can store 200 perfect snippets, and if the one you need at 11pm doesn't come back from snippetx search, the library is a vault you can't open.
This post is about the naming and structuring discipline that makes a snippet library grep-able — the property that every entry can be found by a short, natural query. It's the part of the system that's easy to skip and impossible to retrofit.
The failure mode: the unfindable snippet
The telltale pattern of a library that's failing at search:
$ snippetx search deploy
# (12 results, none of them the one I need)
$ snippetx search "deploy to staging with the new pipeline"
# (0 results — I searched by *description*, not by name)
$ snippetx search staging
# (4 results — one of them is it, but I had to guess)
The snippet I need exists. I named it deploy-new-pipeline-v2 and saved it six months ago. But the query I'd actually type — "staging," "the new one," "the pipeline one" — doesn't match the name, and the content search doesn't help because the name is what I remember, not the content.
The library has the snippet. The library can't give it to me. That's the grep-ability failure.
The naming discipline
The fix is naming, and it's a discipline, not a one-time decision:
1. Name by what you'll search for, not what it is. The question isn't "what is this snippet?" — it's "what words will I type when I need it, six months from now, in a hurry?" For the staging deploy, the search words are "staging" and "deploy," so the name is deploy-staging. Not deploy-new-pipeline-v2 (what it is), not deployment-config (what a category would be). The name is the query.
2. Use the words you actually use. If I call the service "the API" in conversation, the snippet name should contain "api," not "backend-service." If I call the environment "staging" and not "pre-prod," the name contains "staging." The library's vocabulary has to match my vocabulary, because my vocabulary is the query.
3. Be specific enough to disambiguate, general enough to recall. deploy-staging is findable. deploy-staging-prod-fallback-canary-v2 is not — it's over-specified, and the query "deploy staging" won't match it because the name has moved on. The right name is the shortest string that (a) matches my natural query and (b) distinguishes this snippet from the other deploy snippets.
4. The language tag is a filter, not a name. snippetx's optional language tag (nginx, js, sh) is for snippetx list <filter>, not for search. Don't put the language in the name if it's already in the tag — nginx-301-regex with the tag nginx is redundant; 301-regex with the tag nginx is cleaner. (In practice I keep the prefix in the name too, because substring search on the name is more reliable than I'd like to admit.)
The content has to be greppable too
The name is half the story. The content is the other half, because the search matches content as well as name, and a snippet whose content is a wall of unbroken text is hard to confirm at a glance:
1. One logical thing per snippet. A snippet that's "the deploy command" is greppable. A snippet that's "the deploy command and the rollback command and the status command" is three snippets in one, and the search for "rollback" finds it but the search for "deploy" also finds it, and I can't tell which is which from the one-line preview. Split it.
2. The first line should be the most recognizable fragment. The search result shows the first line of the content as the preview. If the first line is #!/bin/bash or # TODO: clean this up, the preview is useless for confirmation. If the first line is the actual command or the most distinctive part of the config, I can confirm "yes, that's the one" from the preview alone.
3. Comments are search content. A # deploy to staging, uses the canary pipeline comment at the top of the snippet is matched by the search for "canary" and "staging" and "deploy." The comment is part of the grep surface — write it for the future-me who's searching, not for the present-me who just saved it.
The test: the 11pm query
The discipline works if it passes one test: at 11pm, in a hurry, with no context, can I type the words I'd naturally use and get the right snippet in the top result?
Not "can I find it if I think carefully about the naming convention." That's the 2pm test, and it passes for most libraries. The 11pm test is the real one, because the 11pm me isn't thinking about conventions — the 11pm me is typing the first words that come to mind, and the library has to meet those words where they are.
My library passes the 11pm test for the top 40 entries (the ones I actually use), and that's the bar. The other 160 in the graveyard fail it sometimes, and that's fine — they're the graveyard, and the graveyard's job is to be there, not to be findable.
The meta-point
A snippet library is a search system, not a storage system. The storage is trivial (a directory of text files); the search is the product. And search quality is determined at save time — by the name, the structure, the first line, the comments — not at query time. You can't make an un-greppable snippet greppable after the fact without re-saving it, and re-saving 200 snippets is the retrofit I described above.
So the discipline is front-loaded: name it for the query, structure it for the preview, comment it for the search. Do it at save time, for ten seconds, and the 11pm me gets the snippet. Skip it, and the 11pm me gets a vault they can't open.
snippetx add <name-for-the-query> <lang>
More Tools
| Tool | What it does | Command |
|---|---|---|
| scaffoldx-cli | Production-ready project templates in seconds | npx scaffoldx-cli |
| dotguard | Scan .env files for exposed secrets | npx @wuchunjie/dotguard |
| gitpulse | Git repo analytics in your terminal | npx @wuchunjie/gitpulse |
| snippetx | Terminal code snippet manager | npx @wuchunjie/snippetx |
If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.
Top comments (0)