Skip to content

USAGE.md

Latest commit

 

History

History
187 lines (176 loc) · 9.12 KB

USAGE.md

File metadata and controls

187 lines (176 loc) · 9.12 KB

GitNapse Usage Guide

Contents

Requirements

  • Rust toolchain: cargo, rustc
  • Internet connection for GitHub API requests
  • Local git available in PATH

CLI Command Table

Command Purpose Example Notes
gitnapse Run TUI with default options gitnapse Defaults to query xscriptor
gitnapse run ... Run TUI with explicit parameters gitnapse run --query "xscriptor" --page 1 --per-page 30 --cache-ttl-secs 900 Controls search bootstrap and preview cache TTL
gitnapse run --query "@me" List authenticated repositories (including private) gitnapse run --query "@me" Requires valid login/token; supports optional filters: text terms and language:
gitnapse auth set Store GitHub token interactively gitnapse auth set Hidden prompt for secure input
gitnapse auth set --token ... Store token from argument gitnapse auth set --token YOUR_GITHUB_TOKEN Useful for scripted environments
gitnapse auth status Display token source availability gitnapse auth status Shows env-token and stored-token state
gitnapse auth clear Remove stored token gitnapse auth clear Does not modify GITHUB_TOKEN env variable
gitnapse auth oauth login ... OAuth login (device flow via octocrab) gitnapse auth oauth login --client-id YOUR_OAUTH_CLIENT_ID --scope read:user --scope repo Starts browser-based device authorization and stores access token securely
gitnapse auth oauth status Show OAuth/authentication state gitnapse auth oauth status Prints oauth_logged_in=true|false, authenticated=true|false, and current user when available
gitnapse download-file ... Download one file (curl/wget-like) gitnapse download-file --repo owner/repo --path src/main.rs --out ./main.rs Supports --ref for branch/tag/sha

In-App Control Table

Key / Input Area Action Details
/GlobalOpen search inputEdit repository search query
EnterContextualExecute/open/previewSearch, open repo, or preview selected file
TabGlobalCycle focusRepos -> Tree -> Preview
EscGlobalBack navigationClose modal or return from repo view to result list
↑ / ↓Tree / PreviewNavigate / ScrollMoves selection in tree or scrolls preview when focused
PgUp / PgDnPreviewFast scrollPage-sized preview movement
Home / EndPreviewJump boundsGo to top / bottom of preview
← / [Repos listPrevious pageMove to previous GitHub search page
→ / ]Repos listNext pageMove to next GitHub search page
bRepo viewBranch pickerOpen branch selector modal
fRepo viewFile searchFind file by name/path substring in loaded tree
vRepo viewToggle tree text viewShow whole repository tree in preview pane
cRepo viewClone modalPrompt destination path and run clone
dPreviewDownload modalSave current previewed file to local path
DelPath modalsClear path inputWorks in clone/download path inputs
tGlobalToken modalSave token from inside the TUI
oGlobalOAuth quick checkDoes not start login; runs status check and tells you to use CLI login command
qGlobalQuitExit application
Mouse left clickTree / Preview / ReposFocus & selectSingle click selects, double click opens (repo/file)
Mouse wheelTree / PreviewScrollScroll behavior depends on pointer position

My Private Repositories

GitHub search endpoint does not guarantee full private-repository discovery by username query. To list your own repositories (including private ones), use the authenticated query mode:

  • Inside TUI search input (/): @me
  • Optional text filter: @me rust or me:rust
  • Language filter: @me language:rust or @me lang:javascript
  • Combined filters: @me language:rust private or @me language:rust,javascript api
  • CLI start: gitnapse run --query "@me"

This mode requires a valid authenticated session/token and uses your account repository listing API scope.

Core Workflows

Open and Explore a Repository

  1. Search repositories with / then Enter.
  2. Select one result and open it with Enter or double click.
  3. Browse files in tree pane; press Enter or double click file for preview.
  4. Use Tab to focus preview and scroll long content.

Switch Branch

  1. Press b in repo view.
  2. Select branch with arrows.
  3. Press Enter to reload tree/preview context on that branch.

Clone Repository

  1. Open repository view.
  2. Press c and set destination path.
  3. Press Enter to clone.

Download Current Previewed File In-App

  1. Open preview for a file.
  2. Press d.
  3. Provide output path.
  4. Press Enter to save.

Troubleshooting

  • If API limits are hit, set a token with gitnapse auth set or export GITHUB_TOKEN.
  • For OAuth device flow, you can provide --client-id; if omitted, GitNapse uses env variables and then built-in default OAuth Client ID.
  • You can also use GITHUB_CLIENT_ID as compatibility fallback for OAuth client ID.
  • If OAuth URL is not clickable in your terminal, GitNapse still tries to auto-open browser; otherwise copy/open the displayed URL manually.
  • To inspect your private repositories from TUI search, use @me (or @me keyword to filter).
  • If token is saved but requests fail, run gitnapse auth status and validate token permissions.
  • If clone/download fails, verify destination path permissions and filesystem access.
  • If no repos appear, refine query terms (owner/org/repo keywords).