docs: 添加项目文档AGENTS.md
添加详细的zoxide项目文档，包含技术栈、项目结构、构建测试命令、代码风格指南、测试说明、安全考虑、架构细节和发布部署信息
This commit is contained in:
soar0216
parent
67ca1bc959
commit
d52c6336b8
|
|
@ -0,0 +1,244 @@
|
||||||
|
# zoxide
|
||||||
|
|
||||||
|
zoxide is a smarter `cd` command for your terminal, inspired by `z` and `autojump`.
|
||||||
|
It remembers which directories you use most frequently, so you can "jump" to them
|
||||||
|
in just a few keystrokes. It works on all major shells.
|
||||||
|
|
||||||
|
This is a Rust CLI project. The repository lives at
|
||||||
|
<https://github.com/ajeetdsouza/zoxide>.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technology stack
|
||||||
|
|
||||||
|
- **Language**: Rust (edition 2024, MSRV 1.85.0)
|
||||||
|
- **CLI parsing**: `clap` v4 with derive macros
|
||||||
|
- **Template engine**: `askama` (for generating shell integration scripts)
|
||||||
|
- **Database serialization**: `bincode`
|
||||||
|
- **Error handling**: `anyhow`
|
||||||
|
- **Self-referencing structs**: `ouroboros` (used by the database layer)
|
||||||
|
- **Task runner**: `just`
|
||||||
|
- **Dev environment**: Nix (`shell.nix`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── Cargo.toml # Package manifest
|
||||||
|
├── build.rs # Generates shell completions into contrib/completions/
|
||||||
|
├── justfile # Task definitions (lint, test, fmt)
|
||||||
|
├── rustfmt.toml # Rustfmt configuration
|
||||||
|
├── shell.nix # Reproducible Nix development shell
|
||||||
|
├── Cross.toml # Cross-compilation configuration
|
||||||
|
│
|
||||||
|
├── src/
|
||||||
|
│ ├── main.rs # Entry point: parses args, runs commands, handles SilentExit
|
||||||
|
│ ├── config.rs # Reads environment variables (_ZO_DATA_DIR, _ZO_ECHO, etc.)
|
||||||
|
│ ├── error.rs # SilentExit and BrokenPipeHandler traits
|
||||||
|
│ ├── util.rs # Fzf wrapper, atomic file writes, path resolution, time utils
|
||||||
|
│ ├── shell.rs # Askama template structs for each supported shell
|
||||||
|
│ │
|
||||||
|
│ ├── cmd/ # CLI subcommand implementations
|
||||||
|
│ │ ├── mod.rs # Run trait and command dispatch
|
||||||
|
│ │ ├── cmd.rs # Clap derive structs for all subcommands and enums
|
||||||
|
│ │ ├── add.rs # `zoxide add` — add/increment directory rank
|
||||||
|
│ │ ├── query.rs # `zoxide query` — search database (list/interactive/first)
|
||||||
|
│ │ ├── init.rs # `zoxide init` — render shell integration script
|
||||||
|
│ │ ├── import.rs # `zoxide import` — import from autojump / z
|
||||||
|
│ │ ├── remove.rs # `zoxide remove` — remove directory from database
|
||||||
|
│ │ └── edit.rs # `zoxide edit` — interactive database editor via fzf
|
||||||
|
│ │
|
||||||
|
│ └── db/ # Database layer
|
||||||
|
│ ├── mod.rs # Database struct (open, save, add, remove, age, dedup, sort)
|
||||||
|
│ ├── dir.rs # Dir struct (path, rank, last_accessed, score, display)
|
||||||
|
│ └── stream.rs # Stream iterator for querying directories with filters
|
||||||
|
│
|
||||||
|
├── templates/ # Askama templates for shell integration scripts
|
||||||
|
│ ├── bash.txt, zsh.txt, fish.txt, powershell.txt, ...
|
||||||
|
│
|
||||||
|
├── contrib/completions/ # Generated completion files (updated by build.rs)
|
||||||
|
│
|
||||||
|
├── man/man1/ # Man pages
|
||||||
|
│
|
||||||
|
└── tests/
|
||||||
|
└── completions.rs # Integration tests for generated completion scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Build and test commands
|
||||||
|
|
||||||
|
### Standard (without Nix)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build debug binary
|
||||||
|
cargo build
|
||||||
|
|
||||||
|
# Build release binary
|
||||||
|
cargo build --release
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
cargo test
|
||||||
|
|
||||||
|
# Run lints
|
||||||
|
cargo clippy --all-features --all-targets -- -Dwarnings
|
||||||
|
|
||||||
|
# Format code
|
||||||
|
cargo fmt --all
|
||||||
|
```
|
||||||
|
|
||||||
|
### With Nix (recommended on Unix)
|
||||||
|
|
||||||
|
The project uses a pure Nix shell for CI and local development. All linting and
|
||||||
|
testing tools are pinned there.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Enter dev shell
|
||||||
|
nix-shell
|
||||||
|
|
||||||
|
# Run lints (includes rustfmt, clippy, msrv, udeps, shellcheck, markdownlint, ...)
|
||||||
|
just lint
|
||||||
|
|
||||||
|
# Run tests (uses cargo-nextest when inside nix-shell)
|
||||||
|
just test
|
||||||
|
|
||||||
|
# Format everything (Rust, Nix, shell, YAML, Markdown)
|
||||||
|
just fmt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Important notes
|
||||||
|
|
||||||
|
- `build.rs` generates shell completions into `contrib/completions/`. It is not
|
||||||
|
a no-op — modifying CLI definitions in `src/cmd/cmd.rs` will regenerate these
|
||||||
|
files on the next build.
|
||||||
|
- The `nix-dev` Cargo feature gates tests that require external binaries
|
||||||
|
(shells, fzf, shellcheck, shfmt, black, mypy, pylint, fish_indent, etc.).
|
||||||
|
These tests only run when the feature is enabled and the tools are available.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code style guidelines
|
||||||
|
|
||||||
|
- Use `cargo fmt` with the project's `rustfmt.toml`.
|
||||||
|
- Key settings:
|
||||||
|
- `group_imports = "StdExternalCrate"`
|
||||||
|
- `imports_granularity = "Module"`
|
||||||
|
- `style_edition = "2024"`
|
||||||
|
- `use_try_shorthand = true`
|
||||||
|
- `use_field_init_shorthand = true`
|
||||||
|
- Prefer `?` and `anyhow::Result` for error propagation.
|
||||||
|
- Use `SilentExit` for intentional early exits that should not print an error
|
||||||
|
message.
|
||||||
|
- Use `BrokenPipeHandler::pipe_exit` when writing to stdout/stderr to handle
|
||||||
|
broken pipes gracefully (e.g. `| head`).
|
||||||
|
- Keep platform-specific code behind `cfg(unix)` / `cfg(windows)`.
|
||||||
|
- Only use `unsafe` when absolutely necessary (the project currently uses it
|
||||||
|
only once, to forcibly disable Rust backtrace environment variables at startup).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing instructions
|
||||||
|
|
||||||
|
### Unit tests
|
||||||
|
|
||||||
|
Embedded in source files under `#[cfg(test)]`:
|
||||||
|
|
||||||
|
- `src/db/mod.rs` — database add/remove persistence
|
||||||
|
- `src/db/stream.rs` — keyword matching algorithm (parameterized with `rstest`)
|
||||||
|
- `src/cmd/import.rs` — autojump and z importer logic
|
||||||
|
|
||||||
|
Run them with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cargo test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration tests
|
||||||
|
|
||||||
|
- `tests/completions.rs` — loads generated completion scripts into bash, fish,
|
||||||
|
zsh, and PowerShell to verify they parse without errors. Requires the
|
||||||
|
`nix-dev` feature.
|
||||||
|
|
||||||
|
### Shell integration tests
|
||||||
|
|
||||||
|
Located in `src/shell.rs` under `#[cfg(feature = "nix-dev")]`.
|
||||||
|
These are the most comprehensive tests: they render every Askama template for
|
||||||
|
all combinations of options and then:
|
||||||
|
|
||||||
|
- Execute the generated script in the actual shell binary (bash, dash, zsh,
|
||||||
|
fish, elvish, nushell, pwsh, tcsh, xonsh)
|
||||||
|
- Run linters on the generated script (shellcheck, shfmt, fish_indent, black,
|
||||||
|
mypy, pylint)
|
||||||
|
|
||||||
|
Because they require many external tools, they are gated behind the `nix-dev`
|
||||||
|
feature and are intended to run inside the Nix shell.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all tests including nix-dev tests
|
||||||
|
nix-shell --pure --run "cargo nextest run --all-features --no-fail-fast --workspace"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **Atomic database writes**: The database is written atomically using a
|
||||||
|
temporary file + `fs::rename` to prevent corruption on crashes. On Unix, the
|
||||||
|
temporary file preserves the original file's owner via `fchown`.
|
||||||
|
- **Windows executable resolution**: On Windows, `fzf.exe` is resolved via the
|
||||||
|
`which` crate before spawning to avoid the current-directory executable search
|
||||||
|
behavior of `CreateProcess`.
|
||||||
|
- **Path validation**: `add` rejects paths containing newlines or carriage
|
||||||
|
returns. Symlink resolution is optional and controlled by `_ZO_RESOLVE_SYMLINKS`.
|
||||||
|
- **Database size limit**: Deserialization enforces a 32 MiB maximum to prevent
|
||||||
|
malformed input from causing excessive memory use.
|
||||||
|
- **Backtrace suppression**: The binary forcibly unsets `RUST_BACKTRACE` and
|
||||||
|
`RUST_LIB_BACKTRACE` at startup to avoid leaking internal paths in error
|
||||||
|
output.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key architectural details
|
||||||
|
|
||||||
|
### Database
|
||||||
|
|
||||||
|
- Stored as a binary file (`db.zo`) in the data directory, serialized with
|
||||||
|
`bincode`. The format has a version header (current version: 3).
|
||||||
|
- Each entry has a `path`, `rank` (f64), and `last_accessed` (Unix epoch).
|
||||||
|
- The `Database` struct is self-referencing (via `ouroboros`) because `Dir`
|
||||||
|
contains a `Cow<'a, str>` borrowed from the deserialized bytes.
|
||||||
|
- Scoring applies time-based multipliers: entries accessed within the last hour
|
||||||
|
get 4x, within a day 2x, within a week 0.5x, older 0.25x.
|
||||||
|
- Aging keeps total rank bounded. When the sum exceeds `_ZO_MAXAGE` (default
|
||||||
|
10000), all ranks are scaled down and entries below rank 1.0 are removed.
|
||||||
|
- Non-existent directories are lazily removed during queries if they have not
|
||||||
|
been accessed within a 3-month TTL.
|
||||||
|
|
||||||
|
### Shell integration
|
||||||
|
|
||||||
|
- `zoxide init <shell>` renders an Askama template from `templates/` to stdout.
|
||||||
|
- The generated script defines `z` (jump), `zi` (interactive jump), and a hook
|
||||||
|
that calls `zoxide add` automatically.
|
||||||
|
- Hook modes: `none` (never), `prompt` (every prompt), `pwd` (on directory
|
||||||
|
change, default).
|
||||||
|
|
||||||
|
### Query flow
|
||||||
|
|
||||||
|
1. Open the database.
|
||||||
|
2. Create a `Stream` with filters (keywords, base_dir, exclude globs, exists check).
|
||||||
|
3. Stream sorts entries by score and returns them one by one.
|
||||||
|
4. For interactive mode, results are piped into `fzf`.
|
||||||
|
5. Save the database (lazy cleanup may mark it dirty).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Release and deployment
|
||||||
|
|
||||||
|
- CI runs on `ubuntu-latest` inside a Nix shell for lints and tests.
|
||||||
|
- The release workflow cross-compiles for many targets (Linux musl, Android,
|
||||||
|
macOS, Windows) using `cross`, packages them as `.tar.gz`, `.zip`, and `.deb`,
|
||||||
|
and uploads artifacts.
|
||||||
|
- A draft GitHub release is automatically created when a commit on `main`
|
||||||
|
starts with `chore(release)`.
|
||||||
Loading…
Reference in New Issue