DEV Community

Yuna
Yuna

Posted on

I built RepoTrek: a terminal-first GitHub source browser in Rust

#cli #opensource #rust #showdev

I built RepoTrek, a terminal-first GitHub source browser written in Rust.

GitHub:

https://github.com/yuna-r/repotrek

crates.io:

https://crates.io/crates/repotrek

The basic idea is simple:

I wanted a comfortable way to deeply explore GitHub repositories without constantly switching between the browser, terminal, and editor.

RepoTrek is not intended to replace Git clients such as git, lazygit, tig, or gitui.

Its focus is different:

Git client
    ↓
operate on a repository

RepoTrek
    ↓
explore and read a repository
Enter fullscreen mode Exit fullscreen mode

Why I built it

When reading open-source projects on GitHub, I often move through a sequence like this:

Code
 ↓
Blame
 ↓
Commit
 ↓
Diff
 ↓
File history
 ↓
Another file
Enter fullscreen mode Exit fullscreen mode

GitHub's web interface is excellent, but when I spend a long time reading source code, I prefer staying in the terminal and using the keyboard.

So I started building a TUI specifically around source code exploration.

No clone required

You can open a repository directly from GitHub.

For example:

rust-lang/rust
Enter fullscreen mode Exit fullscreen mode

or:

torvalds/linux
Enter fullscreen mode Exit fullscreen mode

RepoTrek retrieves the repository information through GitHub APIs, so you don't need to clone the entire repository just to inspect it.

This is especially convenient for quickly looking through large projects.

Features

RepoTrek currently includes:

  • Repository tree browsing
  • Source code viewer with line numbers
  • Syntax highlighting
  • Dark / Light themes
  • Commit history
  • Commit diffs
  • File history
  • Git blame
  • Branch switching
  • File search
  • Repository-wide code search
  • Symbol navigation
  • Definition search
  • Pull Requests
  • Issues
  • GitHub Actions
  • Releases
  • Keyboard-based text selection and copy
  • Source/diff wrapping
  • HTML export for printing

The interface is designed to make moving between these views fast without leaving the terminal.

Source code browsing

The main view works like a terminal-native repository browser.

src/
├── app.rs
├── auth.rs
├── export.rs
├── highlight.rs
├── provider/
└── ui/
Enter fullscreen mode Exit fullscreen mode

Open a file and RepoTrek displays it with line numbers and syntax highlighting.

Common languages such as Rust, Python, JavaScript, TypeScript, C/C++, Go, Java, YAML, TOML, JSON, Shell, HTML, CSS, and Markdown are recognized.

Unknown formats simply fall back to plain text.

Blame and file history

One feature I especially wanted was the ability to move naturally between:

source line
    ↓
blame
    ↓
commit
    ↓
diff
    ↓
history
Enter fullscreen mode Exit fullscreen mode

The current source code often tells you what the program does.

History often tells you why it became that way.

That makes blame and file history important parts of RepoTrek rather than secondary features.

Commit diffs

Commit diffs include both old and new line numbers.

For example:

  81   81     fn example() {
  82          - old_code();
       82     + new_code();
  83   83     }
Enter fullscreen mode Exit fullscreen mode

Added and removed lines also have separate highlighting.

Long source lines and diffs can be wrapped directly inside the TUI.

Search and navigation

RepoTrek provides several ways to move around a repository.

File search

Search files by name and quickly jump to a result.

Code search

Search repository contents and open matching files directly.

Symbol navigation

Inside a source file, @ opens a symbol picker.

For Rust, for example, RepoTrek can identify things such as:

struct
enum
trait
impl
fn
Enter fullscreen mode Exit fullscreen mode

Definition search

Pressing d searches for likely definitions of the identifier around the current cursor position.

This is currently heuristic-based rather than a full LSP implementation.

GitHub information inside the TUI

RepoTrek is gradually bringing more of the GitHub repository experience into the terminal.

It can display information for:

Code
Commits
Pull Requests
Issues
Actions
Releases
Enter fullscreen mode Exit fullscreen mode

When the web interface is still useful, pressing o opens the corresponding GitHub page.

The goal isn't to eliminate the browser completely.

The goal is to make it optional during normal source exploration.

Keyboard-first

I wanted the application to remain usable almost entirely from the keyboard.

For example:

Shift+J    extend selection downward
Shift+K    extend selection upward
Shift+A    select all
Shift+C    copy

v          Vim-style selection
y          copy selection

Esc        clear selection / go back
Enter fullscreen mode Exit fullscreen mode

There are also shortcuts for searching, switching branches, toggling themes, wrapping lines, and opening external GitHub pages.

Dark and Light themes

RepoTrek supports both Dark and Light themes.

The Light theme is not just an inverted Dark theme.

Syntax colors, selected lines, active lines, and diff colors are defined separately so source code remains readable in both modes.

The selected theme is persisted between sessions.

Printing source code from a TUI

One slightly unusual feature is HTML export.

RepoTrek can generate printable HTML for source files and diffs.

Exports include:

  • Syntax highlighting
  • Line numbers
  • Old/new diff line numbers
  • Added/removed line backgrounds
  • Print-oriented layout
  • A4 landscape CSS

Files are automatically written to:

exports/
Enter fullscreen mode Exit fullscreen mode

with timestamped filenames.

I sometimes like reading larger pieces of source code away from the editor, so I wanted RepoTrek to treat printing as a real output format rather than an afterthought.

Built with Rust and Ratatui

RepoTrek is written in Rust and uses Ratatui for the terminal UI.

At a high level, the architecture looks roughly like this:

GitHub API
    ↓
Provider
    ↓
RepoTrek models
    ↓
Application state
    ↓
Ratatui UI
Enter fullscreen mode Exit fullscreen mode

I intentionally keep GitHub-specific API structures away from most of the UI.

The idea is to make support for other Git forges possible later.

Potential future providers could include:

GitLab
Gitea
Forgejo
Enter fullscreen mode Exit fullscreen mode

Cross-platform releases

RepoTrek is built for:

Linux
  x86_64
  ARM64

macOS
  Apple Silicon
  Intel

Windows
  x86_64
  ARM64
Enter fullscreen mode Exit fullscreen mode

Release builds are automated with GitHub Actions.

The project is also available through crates.io:

cargo install repotrek
Enter fullscreen mode Exit fullscreen mode

What's next?

RepoTrek is still a v0.x project, so there are many things I want to improve.

Some ideas include:

  • Better symbol analysis
  • LSP integration
  • Improved commit graphs
  • Better PR review navigation
  • More GitHub Actions information
  • Smarter caching
  • Performance improvements for very large repositories
  • GitLab / Gitea / Forgejo support
  • Better terminal capability detection
  • Mouse support where useful

But the main goal will stay the same:

Make exploring source code from the terminal enjoyable.

Try it

GitHub:

https://github.com/yuna-r/repotrek

crates.io:

https://crates.io/crates/repotrek

Install with Cargo:

cargo install repotrek
Enter fullscreen mode Exit fullscreen mode

If you enjoy Rust, TUIs, open source, or simply reading other people's code, I'd love for you to try it.

Feedback, issues, and pull requests are welcome 🐻🦀

Top comments (0)