{"id":28262481,"url":"https://github.com/atliod/gozelle","last_synced_at":"2026-03-01T05:21:47.220Z","repository":{"id":289346148,"uuid":"962120285","full_name":"ATLIOD/Gozelle","owner":"ATLIOD","description":"A Blazing fast smart cd command written in go","archived":false,"fork":false,"pushed_at":"2025-06-04T21:21:30.000Z","size":1919,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-05T11:35:50.312Z","etag":null,"topics":["bash","command-line-tool","fish","fzf","go","golang","linux","zsh"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ATLIOD.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}},"created_at":"2025-04-07T17:19:21.000Z","updated_at":"2025-06-05T11:11:34.000Z","dependencies_parsed_at":"2025-04-22T20:39:55.704Z","dependency_job_id":"bd6d9856-3b64-4fdb-948a-78bc7568b3c5","html_url":"https://github.com/ATLIOD/Gozelle","commit_stats":null,"previous_names":["atliod/gozelle"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ATLIOD%2FGozelle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ATLIOD%2FGozelle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ATLIOD%2FGozelle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ATLIOD%2FGozelle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ATLIOD","download_url":"https://codeload.github.com/ATLIOD/Gozelle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ATLIOD%2FGozelle/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259072716,"owners_count":22801074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bash","command-line-tool","fish","fzf","go","golang","linux","zsh"],"created_at":"2025-05-20T07:11:50.739Z","updated_at":"2026-03-01T05:21:47.211Z","avatar_url":"https://github.com/ATLIOD.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gozelle\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/ATLIOD/Gozelle?t=1)](https://goreportcard.com/report/github.com/ATLIOD/Gozelle)\n\n**Gozelle** is a lightning-fast and minimal smart cd command written in Go — inspired by [`zoxide`](https://github.com/ajeetdsouza/zoxide). Jump to frequently used directories with just a keyword, powered by **frecency scoring**, **fuzzy matching**, and **shell integration**.\n\n---\n\n## Table of Contents\n\n- [Features](#Features)\n- [Requirements](#Requirements)\n- [Installation](#Installation)\n- [Usage](#Usage)\n- [Environment Variables](#Environment-Variables)\n- [How It Works](#How-it-works)\n- [Learnings \u0026 Concepts](#Learnings--concepts)\n- [Roadmap](#Roadmap)\n- [License](#License)\n\n---\n\n## Features\n\n- **Frecency Scoring** — jump history is ranked by frequency and recency  \n- **Fuzzy Matching** — jump with just a keyword or part of a directory name  \n- **Smart Ranking** — most relevant paths surface first  \n- **Manual Add** — add directories to the index yourself  \n- **Query Mode** — list matching directories without jumping  \n- **Compact Storage** — gob-encoded data stored locally  \n- **Shell Integration** — Bash and Zsh command-line hooks for seamless tracking\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## Requirements\n\n- [Bash](https://www.gnu.org/software/bash/), [Zsh](https://www.zsh.org/), or [Fish](https://fishshell.com/) shell  \n- Gozelle binary in your `$PATH`  \n- go version 1.24+\n- [`fzf`](https://github.com/junegunn/fzf) installed for interactive mode\n\n**Platform Support Notice:**  \n\u003e Gozelle has currently only been tested and verified on Linux systems. While it may work on other Unix-like OSes or Windows, no official support or testing has been done outside of Linux.\n\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## Installation\n\n### Option 1: Build from Source\n\n```bash\ngit clone https://github.com/yourusername/gozelle\ncd gozelle\ngo build -o gozelle .\nsudo mv gozelle /usr/local/bin/\n```\n`/usr/local/bin` can be replace by any directory in your `$PATH`\n\n### Option 2: Use `go install`\n\n```bash\ngo install github.com/atliod/gozelle@latest\n```\n\nMake sure your `$GOPATH/bin` is in your `$PATH` (commonly `~/go/bin`):\n\n```bash\nexport PATH=\"$PATH:$(go env GOPATH)/bin\"\n```\n\n### Add to Shell Startup File\n\nFor **Bash**:\n\n```bash\necho 'eval \"$(gozelle init bash)\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\nFor **Zsh**:\n\n```bash\necho 'eval \"$(gozelle init zsh)\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\nFor **Fish**:\n\n```bash\necho 'gozelle init fish | source' \u003e\u003e ~/.config/fish/config.fish\nsource ~/.config/fish/config.fish\n```\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## Usage\n\n### Jump to a Directory\n\n```bash\ngz projects       # jumps to the best match (e.g., ~/Documents/School/Programming/projects)\n```\n\n### Show Matching Directories (without jumping)\n\n```bash\ngozelle query projects\n```\n\n### Add a Directory Manually\n\n```bash\ngozelle add /some/path/to/add\n```\n### Interactive Mode\n```bash\ngi\n```\n\n[↑ Back to top](#Gozelle)\n\n---\n## Environment Variables\n\n| Variable          | Description                                                                                 | Default                                                                                           |\n|-------------------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|\n| `GOZELLE_ECHO`    | Whether to print the target directory path to stdout after jumping. Must be `\"true\"` or `\"false\"`. | `\"false\"` (default)                                                                             |\n| `GOZELLE_DATA_DIR`| Path to the directory where Gozelle stores its data file (`db.gob`). If not set, defaults to: \u003cbr\u003e `$XDG_DATA_HOME/gozelle/db.gob` \u003cbr\u003e or `\u003chome\u003e/.local/share/gozelle/db.gob` if `$XDG_DATA_HOME` is unset. | `~/.local/share/gozelle/db.gob` (default)                                                       |\n\n### Notes\n\n- `GOZELLE_ECHO` must be set to exactly `\"true\"` or `\"false\"`. Any other value will reset it to `\"false\"` and print a warning.\n- When `GOZELLE_DATA_DIR` is set to a non-existent directory, Gozelle will attempt to create the directory automatically in the uses default data directory. ~/.local/share in linux)\n- The environment variable `GOZELLE_DATA_DIR` refers to a directory; the actual data file is stored inside it as `db.gob`.\n\n### Example usage\n\n```bash\nexport GOZELLE_ECHO=true\nexport GOZELLE_DATA_DIR=\"$HOME/.config/gozelle\"\n```\n\n---\n\n## How It Works\n\n- Enables shell hooks for automatic logging via `init bash` or `init zsh`  \n- Tracks every visited directory using the shell hook  \n- Stores them in a gob-encoded file under your user data directory (default is `~/.local/share/Gozelle` for Linux users)  \n- Finds all matches for keywords entered, e.g., `gz keywords`  \n- Ranks them using a **frecency** score (frequency + recency)\n- Uses fzf to provide an interactive selection UI when requested\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## Learnings \u0026 Concepts\n\nThis project is a hands-on learning opportunity for:\n\n- **Concurrency** — handling simultaneous updates and queries efficiently  \n- **Worker Pools** — to process background updates to scoring  \n- **Mutexes** — for safe access to shared resources (like the gob database)  \n- **Command Line Hooks** — shell integration and behavior injection  \n- **Gob Encoding** — simple and efficient binary data serialization in Go\n- **Integration with External Tools** — incorporating fzf for interactive mode\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## Roadmap\n\n- [X] Zsh support  \n- [X] Fish shell support  \n- [X] Interactive `fzf`-style selector  \n- [X] Configurable data file location  \n- [X] Directory expiration / pruning logic  \n- [X] Man Page  \n- [X] Completion support\n- [ ] Better pruning logic\n- [X] Higher weight to paths where the keyword is closer to the end\n\n[↑ Back to top](#Gozelle)\n\n---\n\n## License\n\n\nGNU General Public License 3.0 — see [LICENSE](LICENSE) for details.\n\n\n[↑ Back to top](#Gozelle)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatliod%2Fgozelle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatliod%2Fgozelle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatliod%2Fgozelle/lists"}