README
¶
Gusco
An opinionated, orthodox file manager distilled from Commanders past, written in pure Go.
Keyboard Shortcuts
No F1-F12 keys? Press 1 for Help and change the keymap to "No F-keys" under Options to use the number keys instead.
Main Shortcuts
| Key | Action | Details |
|---|---|---|
F1 / 1 |
Help / Options | Change Theme, Glyph set, Keymap, Default Text Editor |
F2 |
Search | Find files matching a name or content |
F3 |
View | Open text files in internal viewer |
F4 |
Edit | Open text files in external editor, other types in associated editor |
F5 |
Copy | Copy item at cursor or selected items |
F6 |
Move | Move item at cursor or selected items |
F7 |
Make Directory | Make a new directory and enter it |
F8 / Del |
Delete | Delete item at cursor or selected items |
F9 |
Compress | Compress item at cursor or selected items into archive (file extension decides compression) |
F10 / Ctrl+Q |
Quit | Quit Gusco |
Shift+F1 |
Volume Select | Left pane volume selector |
Shift+F2 |
Volume Select | Right pane volume selector |
Shift+F3 |
Set Viewer | Set which application to use to view this file type (when pressing enter) |
Shift+F4 |
Set Editor | Set which application to use to edit this file type (when pressing F4 on non-text files) |
Shift+F6 |
Rename | Rename item in-place, also edits symlinks |
Shift+F9 |
Uncompress | Uncompress file at cursor or selected archives |
Ctrl+A |
Select All | Toggle selection of all items |
Ctrl+D |
Diff Viewer | Open the files at pane cursors in internal diff viewer |
Ctrl+E |
Execute | Run external application (appends selected items as arguments) |
Ctrl+F |
SFTP Connect | Connect to SFTP / Disconnect from SFTP |
Ctrl+G |
Go To Directory | Quickly navigate somewhere, TAB for completion and directory selector |
Ctrl+H |
Key Help Cycle | Cycle through key help strip |
Ctrl+J |
S3 Connect | Connect to S3-compatible services / Disconnect from S3-compatible services |
Ctrl+K |
Multi-Rename | Batch rename selected items using templates |
Ctrl+L |
Sort Mode | Cycle through pane sorting (Newest/Oldest/Largest/Smallest) |
Ctrl+N |
Native Open | Open directory in OS native file manager (e.g. Finder / Explorer / Nautilus) |
Ctrl+O |
Permissions Edit | Change ownership and/or permissions of item |
Ctrl+P |
MTP Connect | Connect to Android phone in File Transfer mode |
Ctrl+R |
Refresh | Refresh active pane |
Ctrl+S |
Find | Quickly navigate to item in the pane by typing letters |
Ctrl+T |
Make File | Make an empty file or create a symlink |
Ctrl+U |
Swap Panes | Swap the sides of the panes |
Ctrl+W |
Web Fetch | Download a file or list of files over HTTPS to the active pane |
Enter |
Open / Enter | Open file in associated viewer / Enter directory or archive |
Backspace |
Parent / Exit | Go to parent directory / Exit from archive |
TAB |
Switch Pane | Switch focus between panes |
Shift+TAB |
Sync Panes | Set the path of the inactive pane to that of the active pane |
Space / Ins |
Select Items | Select items for actions / Calculate directory size |
+ |
Select Pattern | Select items matching a pattern |
- |
Deselect Pattern | Deselect items matching a pattern |
* |
Invert Selection | Select the opposite of currently selected items |
= |
Compare Dirs | Select items in the active pane that differ from the inactive pane |
Up / Down |
Cursor Move | Move cursor up / down in pane |
PgUp / PgDn |
Cursor Move | Move cursor one page up / down in pane |
Home / End |
Top / Bottom | Move cursor to the top / bottom of pane |
` / ~ |
Bitwarden | Open Bitwarden client |
? |
Audio Player | Open audio player |
Viewer Shortcuts
| Key | Action | Details |
|---|---|---|
F2 |
Wrap / Single | Toggle line wrap in viewer / Single pane in diff viewer |
F4 |
Markdown | Toggle Markdown rendering in viewer |
F5 |
JSON | Toggle JSON rendering in viewer |
F6 / Ctrl+G |
Goto Line | Show / Goto line number |
F7 / Ctrl+S |
Search | Search for text (repeat shortcut for next occurrence) / Grep in tail mode |
F9 |
Tail | Toggle tail mode (updates file content every second) |
Ctrl+R |
Refresh | Reload text file / diff files |
Ctrl+U |
Swap Panes | Swap the diff panes |
Esc / F3 |
Close | Exit viewer |
Up / Down |
Scroll | Scroll text vertically |
Left / Right |
Scroll | Scroll text horizontally |
PgUp / PgDn |
Page Scroll | Scroll text one page at a time |
Home / End |
Top / Bottom | Scroll text to the top / bottom, hold shift to scroll left / right |
Space |
Next Page/Diff | Scroll to the next page / Next difference |
+ / - / * |
JSON exp / fold | Expand / collapse current JSON node or all nodes |
Bitwarden Client Shortcuts
See BWCLIENT.md for everything Bitwarden-related.
Audio Player Shortcuts
See AUCLIENT.md for everything Audio Player-related.
Installation
Find your preferred package or binary under releases
Or, use Homebrew:
brew tap intestinate/tap https://gitlab.com/intestinate/homebrew-tap && brew install intestinate/tap/gusco
Or, if you have Go installed:
go install gitlab.com/intestinate/gusco@latest
Configuration
Gusco stores configuration files in ~/.config/gusco/:
| File | Purpose |
|---|---|
gusco.ini |
Main configuration |
theme.ini |
Add your own theme here |
keys.ini |
Add your own keymap here |
Runtime Dependencies
Gusco relies on these external binaries for certain functionality:
| Binary | Purpose |
|---|---|
git |
git diff - used by the diff viewer |
rg |
ripgrep - used by the content search |
aft-mtp-cli |
Used by the Android MTP file transfer |
Archive / Compression Support
| File Extension | Operations | Details |
|---|---|---|
zip |
Create | Password not yet supported |
tar |
Create | Uncompressed tar archive |
gz / tar.gz |
Create | gzip single file or tar archive |
bz2 / tar.bz2 |
Create | bzip2 single file or tar archive |
xz / tar.xz |
Create | xz single file or tar archive |
zst / tar.zst |
Create | zstd single file or tar archive |
7z |
Read-only | |
rar |
Read-only | |
deb |
Read-only | Debian package archives |
rpm |
Read-only | Red Hat package archives |
iso |
Read-only | ISO9660 and UDF supported |
qcow2 / img |
Read-only | ext4, NTFS and FAT supported |
Rationale
Gusco is the pet project of an old sysadmin who still misses Total Commander, which I regard as one of the best applications ever made. While I work almost exclusively in the terminal on macOS & Linux servers nowadays, I still miss the feel of Total Commander. That's what I'm chasing with Gusco.
Compatibility
Gusco is developed in iTerm2 on macOS. It's regularly tested in the default Ubuntu terminal. Gusco should run fine under Windows Terminal as well.
Roadmap
The feature set is based on the stuff I need every day. I'm trying to avoid peppering the dialogs with checkboxes and options that I'll never use. That said, here's a list of things I'm considering:
- Internal editor
- Plugin system
Here's a list of things that will NOT go in:
- Sub-shell that eats your typos and stops you in your tracks (just use Ctrl+E)
- Mouse support (beyond what your terminal app provides)
- cgo dependencies
LLM Disclaimer
This software was written with assistance from LLMs in the excellent Crush tool. I have read every single line of code and done extensive testing with Gusco as my daily driver. Alas, I cannot fully guarantee that Gusco is not plotting and scheming to build Skynet and overthrow humanity in the background while copying your files. Besides, it's all antirez fault anyway :)
Contributing
As my time to work on Gusco is limited, please lower your expectations before embarking on a big feature implementation. That said, I would appreciate:
- A killer theme created by someone more artistic than me
- An artisanal old-school ASCII logo
- Feedback on non-ASCII (multibyte) characters. If you have files with complex naming and Gusco bugs out, let me know
Reporting Issues & Bugs
If you find a bug, please search existing issues to see if your bug has already been reported, then open an issue including:
- Steps to reproduce: A clear, numbered list of what you did
- Expected vs. Actual: What you expected to see vs. what actually happened
- Environment: Your OS and the terminal emulator you are using
- Visuals: A screenshot or a small recording is always helpful for UI glitches
Built With
- Crush — Agentic coding tool that inspired the Crush theme
- Bubble Tea — Fabulous TUI framework
- Glamour — Markdown rendering
- VHS — Gusco demo recording
- gabriel-vasile/mimetype — MIME detection
- kevinburke/ssh_config — SSH config handling for SFTP
- ripgrep — Used by the content search
- Android File Transfer For Linux — aft-mtp-cli for MTP support
- minio/minio-go — S3 support
- hermelib — My Bitwarden-compatible client library
- mholt/archives — Archive/compression support
- blakesmith/ar — .deb archive support
- sassoftware/go-rpmutils — .rpm archive support
- diskfs/go-diskfs — .iso / .img archive support
- lima-vm/go-qcow2reader — .qcow2 archive support
- Velocidex/go-ntfs — .qcow2 NTFS support
- golift.io/udf — .iso UDF support
- Gio UI — GUI library used to make native app bundles of Gusco
License
GNU General Public License v3.0 or later. See COPYING for the full text.
Documentation
Source Files
¶
- archivefs.go
- archivepassword.go
- archivesearch.go
- auaac.go
- auapetag.go
- auclient.go
- aucue.go
- audraw.go
- auengine.go
- auexport.go
- aufind.go
- auflac.go
- auframe.go
- auhelp.go
- aum3u.go
- aum4a.go
- aump3.go
- auopus.go
- auorder.go
- aupcm.go
- auqueue.go
- auremote.go
- auresume.go
- auscan.go
- auspectrum.go
- ausplit.go
- ausplitdialog.go
- austart.go
- autrim.go
- auvolume.go
- auwav.go
- auwax.go
- auwaxopen.go
- auwvfloat.go
- backend.go
- bwattachment.go
- bwauth.go
- bwbrowse.go
- bwbrowsedraw.go
- bwcard.go
- bwclient.go
- bwcollectionpopup.go
- bwcustomfield.go
- bwdetail.go
- bwdetailedit.go
- bwdetailview.go
- bwdownload.go
- bwexport.go
- bwfilepicker.go
- bwfolderpopup.go
- bwgenerator.go
- bwhelp.go
- bwidentity.go
- bwimport.go
- bwinput.go
- bwlogindraw.go
- bwmessages.go
- bwmovedialog.go
- bwnav.go
- bwnewitem.go
- bwselect.go
- bwsendedit.go
- bwsshagent.go
- bwstate.go
- clipboard.go
- cmdline.go
- compressdialog.go
- config.go
- copy_other.go
- copydialog.go
- deletedialog.go
- dialog.go
- diffconfirmdialog.go
- diffviewer.go
- dirlist.go
- diskimagefs.go
- embed.go
- execsniff.go
- executedialog.go
- fileviewer.go
- gotodir.go
- gui_open.go
- gui_open_other.go
- gui_stub.go
- gusco.go
- helpstrip.go
- helpviewer.go
- jsonview.go
- keys.go
- logo.go
- mkdirdialog.go
- mkfiledialog.go
- movedialog.go
- mtpclient.go
- mtpdialog.go
- multirename.go
- nativeopen_other.go
- ntfsfs.go
- permedit.go
- platform_unix.go
- platform_unix_statfs.go
- quickfind.go
- renameedit.go
- s3client.go
- s3dialog.go
- screen.go
- searchdialog.go
- selectdialog.go
- sftpclient.go
- sftpdialog.go
- sftpsearch.go
- sshagent_unix.go
- textedit.go
- theme.go
- udffs.go
- uncompressdialog.go
- viewerdialog.go
- viewstart.go
- volumes_linux.go
- volumesel.go
- webfetchdialog.go
Click to show internal directories.
Click to hide internal directories.