{"id":50359290,"url":"https://github.com/rahulsamant37/quickref","last_synced_at":"2026-05-30T00:03:31.674Z","repository":{"id":350736426,"uuid":"1206031016","full_name":"rahulsamant37/quickref","owner":"rahulsamant37","description":"A terminal-first knowledge base for developers who want fast note capture and retrieval with plain Markdown files.","archived":false,"fork":false,"pushed_at":"2026-05-01T07:15:33.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T09:20:28.425Z","etag":null,"topics":["cheatsheet","fuzzy-finder","helper","neovim","notes-keeper","quickreference","shell","templates"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rahulsamant37.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T14:04:45.000Z","updated_at":"2026-05-01T07:15:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rahulsamant37/quickref","commit_stats":null,"previous_names":["rahulsamant37/quickref"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rahulsamant37/quickref","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulsamant37%2Fquickref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulsamant37%2Fquickref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulsamant37%2Fquickref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulsamant37%2Fquickref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rahulsamant37","download_url":"https://codeload.github.com/rahulsamant37/quickref/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahulsamant37%2Fquickref/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33675019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cheatsheet","fuzzy-finder","helper","neovim","notes-keeper","quickreference","shell","templates"],"created_at":"2026-05-30T00:03:31.592Z","updated_at":"2026-05-30T00:03:31.656Z","avatar_url":"https://github.com/rahulsamant37.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# quickref\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Shell: Bash](https://img.shields.io/badge/shell-bash-121011.svg?logo=gnu-bash)](https://www.gnu.org/software/bash/)\n[![Editor: Neovim](https://img.shields.io/badge/editor-neovim-57A143.svg?logo=neovim\u0026logoColor=white)](https://neovim.io/)\n[![Search: ripgrep](https://img.shields.io/badge/search-ripgrep-CF242E.svg?logo=ripgrep\u0026logoColor=white)](https://github.com/BurntSushi/ripgrep)\n[![Fuzzy Finder: fzf](https://img.shields.io/badge/fuzzy%20finder-fzf-0E8A16.svg)](https://github.com/junegunn/fzf)\n[![Notes: Markdown](https://img.shields.io/badge/notes-markdown-000000.svg?logo=markdown)](https://www.markdownguide.org/)\n\nA terminal-first knowledge base for developers who want fast note capture and retrieval with plain Markdown files.\n\n## Overview\n\nquickref is a lightweight Bash toolkit that turns a folder of Markdown notes into a fast, searchable reference system. It is designed for people who already live in the terminal and want information in seconds.\n\nInstead of introducing a new app, database, or sync format, quickref works directly with files you own. Your notes stay portable, readable, and easy to version with Git.\n\nThe workflow is intentionally simple: use `qnewref` to create structured dated notes, then use `qref` to find and open what you need quickly. If you prefer shorter commands, `ref` is a thin wrapper around `qref`.\n\nThis makes quickref a good fit for engineering notes, incident runbooks, setup snippets, and recurring debugging commands where speed and low friction matter.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Why quickref](#why-quickref)\n- [Features](#features)\n- [Philosophy](#philosophy)\n- [Project Structure](#project-structure)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Neovim Integration (Optional)](#neovim-integration-optional)\n- [Performance](#performance)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why quickref\n\n- Fast retrieval from terminal with one command.\n- Low cognitive load: plain files, simple scripts, predictable behavior.\n- No database layer, no migration concerns, no vendor lock-in.\n- Git-friendly workflow for history, diffs, and backups.\n- Easy to script and automate in your existing shell environment.\n\n## Features\n\n- Interactive note picker with preview.\n- Full-text search via ripgrep and jump to first matching line.\n- Date-based note creation with clean slugs.\n- Optional non-interactive mode for scripts and automation.\n- Configurable note root and UI behavior through environment variables.\n- Neovim-first editing with terminal-native flow.\n\n## Philosophy\n\n- Keep notes as files, not records in a hidden store.\n- Prefer speed and clarity over feature bloat.\n- Make the default path useful, then allow opt-in customization.\n\n## Project Structure\n\n```text\nquickref/\n├── bin/\n│   ├── qref\n│   ├── qnewref\n│   └── ref\n├── notes/\n│   ├── index.md\n│   └── ...\n└── templates/\n    └── note.md\n```\n\n## Requirements\n\n- `bash` (all scripts use Bash)\n- `nvim` required by `qref`; used by `qnewref` when opening notes interactively\n- `rg` (ripgrep) required for `qref \u003cquery\u003e` mode\n- `fzf` recommended for interactive selection\n- `fd` optional for faster file discovery in picker mode\n\n## Installation\n\n1. Clone and enter the repository:\n\n```sh\ngit clone \u003cyour-repo-url\u003e \"$HOME/github/quickref\"\ncd \"$HOME/github/quickref\"\n```\n\n2. Ensure scripts are executable:\n\n```sh\nchmod +x bin/qref bin/qnewref bin/ref\n```\n\n3. Configure your shell environment.\n\nZsh:\n\n```sh\ncat \u003c\u003c'EOF' \u003e\u003e ~/.zshrc\nexport QUICKREF_DIR=\"$HOME/github/quickref\"\nexport PATH=\"$QUICKREF_DIR/bin:$PATH\"\n\nalias ref='qref'\nalias qn='qnewref'\nEOF\n\nsource ~/.zshrc\n```\n\nBash:\n\n```sh\ncat \u003c\u003c'EOF' \u003e\u003e ~/.bashrc\nexport QUICKREF_DIR=\"$HOME/github/quickref\"\nexport PATH=\"$QUICKREF_DIR/bin:$PATH\"\n\nalias ref='qref'\nalias qn='qnewref'\nEOF\n\nsource ~/.bashrc\n```\n\n4. Verify:\n\n```sh\nqref --help\nqnewref \"quickref setup test\"\n```\n\n## Usage\n\n| Command | Behavior |\n|---|---|\n| `qref` | Interactive note picker from `notes/` (excludes `notes/index.md`) |\n| `qref \u003ctext\u003e` | Search in `notes/`, let you choose a matching markdown file with preview, then open it |\n| `qref stl` | Open `notes/commands/cpp-stl/index.md` |\n| `qref stl-list` | Print supported STL quick-access topics |\n| `qref vector` | Jump to the `vector` section in STL quick reference |\n| `qref --help` | Open `notes/index.md` |\n| `qnewref \"title\"` | Create/open `notes/YYYY/MM/YYYY-MM-DD-title.md` |\n| `ref` | Pass-through wrapper to `qref` |\n\nReal-world examples:\n\n```sh\n# Find Docker networking notes and open at first hit\nqref docker network\n\n# Create a dated incident note\nqnewref \"postgres timeout incident\"\n\n# Script-friendly search output (do not open Neovim)\nQUICKREF_NO_OPEN=1 qref ssh tunnel\n```\n\n## Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `QUICKREF_DIR` | `$HOME/github/quickref` | Root directory for quickref |\n| `QUICKREF_NOTES_DIR` | `$QUICKREF_DIR/notes` | Notes directory used by `qref` |\n| `QUICKREF_NO_FZF` | `0` | Disable fzf and auto-pick first file/match |\n| `QUICKREF_NO_PREVIEW` | `0` | Disable split preview in fzf |\n| `QUICKREF_NO_OPEN` | `0` | Print path (or path:line) instead of opening Neovim |\n\nExamples:\n\n```sh\nexport QUICKREF_DIR=\"$HOME/github/quickref\"\nexport QUICKREF_NOTES_DIR=\"$HOME/github/quickref/notes\"\n\nQUICKREF_NO_FZF=1 qref dijkstra\nQUICKREF_NO_PREVIEW=1 qref \"kernel panic\"\nQUICKREF_NO_OPEN=1 qnewref \"release checklist\"\n```\n\nNote: `qnewref` currently writes new notes under `$QUICKREF_DIR/notes`.\n\n## Neovim Integration (Optional)\n\nIf your Neovim config exposes quickref commands, typical usage is:\n\n- `:QuickrefFiles` to browse notes\n- `:QuickrefGrep` to search notes\n- `:QuickrefOpen` to open the project README\n- `:QuickrefNew [title]` to create a new dated note\n\nTypical keymaps:\n\n- `\u003cleader\u003esq` browse notes\n- `\u003cleader\u003esQ` grep notes\n- `\u003cleader\u003eqo` open quickref README\n- `\u003cleader\u003eqn` create note\n\n## Performance\n\n| Task | quickref | Traditional Notes |\n|---|---|---|\n| Open note | Instant | Slower |\n| Search | ripgrep (fast) | Often slower |\n| Setup | Minimal | Heavier |\n\nOptional chart snippet:\n\n```md\n![Performance](assets/metrics.png)\n```\n\n\u003e quickref focuses on speed and minimal overhead for everyday workflows.\n\n## Troubleshooting\n\n| Error | Cause | Fix |\n|---|---|---|\n| `quickref directory not found: ...` | `QUICKREF_DIR` is wrong or the repository is missing | Set `QUICKREF_DIR` to the correct path |\n| `quickref notes directory not found: ...` | `QUICKREF_NOTES_DIR` points to a missing directory | Create the directory or fix `QUICKREF_NOTES_DIR` |\n| `nvim is required but not found in PATH` | Neovim is not installed or unavailable in PATH | Install Neovim and confirm `nvim` resolves |\n| `ripgrep (rg) is required for search mode.` | `rg` is not installed | Install ripgrep |\n| `No matches for: ...` | Query did not match any notes | Broaden your query or create a new note |\n| `No note files found under: ...` | Notes directory is empty | Add notes or verify your notes path |\n\n## Contributing\n\nContributions are welcome and appreciated.\n\n- Keep changes simple, portable, and easy to review.\n- Preserve CLI behavior unless you clearly document changes.\n- Prefer small, focused pull requests.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahulsamant37%2Fquickref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahulsamant37%2Fquickref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahulsamant37%2Fquickref/lists"}