Fri January 5, 2024

Usage

Table of Contents

[TODO]

Hotkeys: ctrl vs. cmd

Hucksh has both macOS and Linux clients. (Windows version forthcoming.) As you may know, Macs have a “command” or “cmd” key in addition to “ctrl” and “opt” (aka “alt”). In general, if a shortcut on macOS uses the Cmd key, on Linux it will use Ctrl; ditto “opt” vs “alt”.

Overview

The gui starts with three tabs, DIRS, HIST, and a shell tab.

The shell tab is where you run commands.

The DIRS tab is the hucksh directory browser. You can navigate around your filesystem with the mouse or various hotkeys, go “back” and “forward” in your history, select files to easily copy their names to the clipboard, or edit them.

The HIST tab shows every directory you’ve ever visited in a shell tab. You can click on directories to display them in the DIRS tab, or move the selection caret up and down with Cmd-Up & Cmd-Down (Linux: Ctrl-Up & Ctrl-Down), or filter using the top textbox.

Running without a license: Trial Mode

If you haven’t installed a license (available here: https://huckridgesw.onfastspring.com/hucksh-license), the app will run in “trial mode”, which means it will only open a single top-level window, and only two shell tabs are allowed.

Navigating tabs

  • Click on the tabs themselves to change tabs.
  • Certain keys (typically Enter) on the DIRS or HIST tabs will switch back to the active shell tab (the one with a “*” next to its name).
  • Click the “X” on the left side of a tab to close it. If there’s only one shell tab, it won’t have the “X”.

A shell tab takes a second or so before it becomes the “active” tab, or click the mouse anywhere in the window.

Tab bar hotkeys

macOSLinuxMeaning
Cmd-Shift-[
Cmd-{
Ctrl-Shift-[
Ctrl-}
Activate tab to the left
Cmd-Shift-]
Cmd-}
Ctrl-Shift-]
Ctrl-}
Activate tab to the right
Cmd-1Ctrl-1Activate the DIRS tab
Cmd-2Ctrl-2Activate the HIST tab
Cmd-3 – Cmd-8Ctrl-3 – Ctrl-8Activate shell tabs 3-8
Cmd-9Ctrl-9Activate the last shell tab
Cmd-TCtrl-TOpen a new shell tab
Cmd-WCtrl-WClose the current shell tab
Popped-out command: Close the window
Cmd-Shift-WCtrl-Shift-WClose the whole window
Tab bar hotkeys

A note about shell tabs: In trial mode (running without a license installed), you only get two shell tabs.

Shell tab – running commands

Command entry overview

You enter commands at the bottom of a shell tab. Type in the command and press Enter to run it. Use regular cursor keys to move around and edit. You can select, cut, copy, and paste, and there’s a rudimentary undo/redo feature.

If a command is running and you want to start entering another one, press Cmd-Shift-& (macOS) or Ctrl-Shift-& (Linux).

Press Cmd/Ctrl-Up/DownArrow or Cmd/Ctrl-P/N to go backwards & forwards in your command history.

See below for more hotkeys.

Interacting with running commands

Some of this is admittedly still suboptimal.

Once you’ve submitted a command, it starts in its own panel, with its own TTY and stdin & stdout. All “control characters” (Ctrl-C, etc) are sent to the running command as you’d expect. You can also press the “Cancel/INT/Kill” button to abort the command.

(Full disclosure: ^C and the “Cancel/INT/Kill” buttons don’t always work. Sometimes to abort something you just have to find the command’s pid and kill it. I’m still working on that.)

If you run a command that wants to read from the “controlling terminal” (like “sudo”, which wants to read your password, or “less”), the command will appear to just hang. Go to the terminal where you’re running the server and enter whatever it’s looking for.

The command panel has full xterm-256color terminal emulation, via Darktile. The interaction between Darktile & hucksh is not yet perfect, but I’m working on it.

The command panel has no cursor yet. This is usually only a problem with interactive programs.

Command directories are clickable

Each command panel shows the directory the command was started in. You can click on any component of any of those directories to change the shell’s current directory to the clicked path. E.g. if you were in /home/you/some/directory and you ran some command and then you clicked on “you”, the shell’s current directory would switch to “/home/you”.

Command buttons

The buttons across the top of the command entry widget by default work on the last command in the tab. If a different command is selected (it’ll be highlighted with a red box), then they work on the highlighted command.

ButtonMeaning
Wrap/NowrapWrap or don’t wrap long lines (still a bit buggy)
ZoomOpen the command in a new full-window tab of its own
PopoutOpen the command in a new top-level window
Hide/UnhideHide or unhide the output of the command
RemoveRemove the command from the tab
Copy cmdCopy the command text to the system clipboard
Copy outputCopy the command output to the system clipboard
Copy bothCopy both the command and the output to the system clipboard
Edit outputOpen the command output in a local editor (requires some configuration)
Paste cmdPaste the command text into the command textbox (but don’t run it)
cd & runcd to the directory of the selected command and run the command again
Command buttons

In a popped-out command, the Cmd/Ctrl-W key will close the window.

You can “popout” a command more than once. This can be handy to look at different parts of the output of the command at the same time.

Command entry hotkeys

macOSLinuxMeaning
EnterEnterRun the command in the given directory
Cmd-Up
Cmd-P
Ctrl-Up
Ctrl-P
Display the previous command in the editor
Cmd-Down
Cmd-N
Ctrl-Down
Ctrl-N
Display the next command in the editor
Cmd-RCtrl-RRe-run the previous command (ignores the currently entered command)
Cmd-ECtrl-EEdit the command in an external editor (requires some configuration)
Command entry hotkeys

Editing the command in an external editor writes the current command to a temp file, opens the tempfile in an editor (via “hucksh-edit local /path/to/file”), waits for the editor to exit, and replaces the current contents of the command editor with the contents of the tempfile.

The external editor is independent of the hucksh gui. If you so desire, you can go on and run other commands and generally use the gui in the usual way. When the external editor exits, the above process continues, even if you’ve started several other commands in the meantime.

Shell tab hotkeys

macOSLinuxMeaning
EnterEnterRun the command
Shift-EnterShift-EnterInsert a newline into the current command
Cmd-RCtrl-RRe-run the selected command, in the same directory
Cmd-3…8Ctrl-3…8Switch to the given shell tab, 3-8
Cmd-9Ctrl-9Switch to the last shell tab
Cmd-U (see warning)Ctrl-UGo up one directory
Cmd-/Ctrl-/Open the command history search panel (see below)
Cmd-HomeCtrl-HomeScroll to the top
Cmd-EndCtrl-EndScroll to the bottom
Cmd-PgUpCtrl-PgUpScroll up one page
Cmd-PgDnCtrl-PgDnScroll down one page
Cmd-Shift-UpCtrl-Shift-UpSelect the previous command, sort of
Cmd-Shift-DownCtrl-Shift-DownSelect the next command, sort of
Cmd-Shift-&Ctrl-Shift-&Display the command editor window (“background” the current command)
Cmd-Shift-DCtrl-Shift-DShow the current directory in the DIRS tab
Cmd-Shift-CCtrl-Shift-CCopy the current command to the system clipboard, in the cmd editor, or for the currently-highlighted command.
Cmd-Shift-ECtrl-Shift-EEdit the current command output in an external editor
Ctrl-CCtrl-CClear the command editor
Ctrl-DCtrl-DDisplay or dismiss the completion widget
Cmd-TCtrl-TOpen a new tab in the current directory
Cmd-WCtrl-WClose the current tab (except the last tab), or “zoomed” command, or popout window.
Cmd-Shift-WCtrl-Shift-WClose the current window
Shell tab hotkeys

Warning: If you’re on a Mac, in a VirtualBox VM, and you press Cmd-U, this is the default VirtualBox hotkey to shutdown the VM. This can be annoying, to say the least.

Shell completion panel

The completion widget will complete environment variables, filenames, command names, and function names.

macOSLinuxMeaning
Ctrl-DCtrl-DDisplay or dismiss the completion widget
ESCESCDismiss the completion widget
Cmd-RCtrl-RRefresh the current completions
TabTabMove to the next completion
Shift-TabShift-TabMove to the previous completion
EnterEnterChoose the current completion
Shell completion panel hotkeys

And of course you can click on any completion to choose it directly.

Shell history search panel

The history panel shows every command you’ve ever run and the directory you ran it in. Typing text into the textbox at the bottom filters the list to commands matching the given regex.

If there’s text in the command entry textbox, the history will be pre-filtered using the given text as a regex to be searched for.

ButtonMeaning
CopyCopy the command into the system clipboard
PastePaste the command into the hucksh command editor (without overwriting what’s there)
cd & pasteCD to that command’s directory and paste the command into the hucksh command editor
cd & runCD to that command’s directory and run the command
Shell history search panel buttons

Hotkeys

macOSLinuxMeaning
ESCESCClear the filter box, or (if already empty) dismiss the search panel
EnterEnterDismiss the panel & set the command editor to the current command
Cmd-EnterCtrl-EnterLike pressing “cd & run” (see above)
Ctrl-CCtrl-CClear the filter box
Cmd-UpCtrl-UpSelect the previous command
Cmd-DownCtrl-DownSelect the next command
Cmd-HomeCtrl-HomeScroll to the top
Cmd-EndCtrl-EndScroll to the bottom
Cmd-PgUpCtrl-PgUpScroll up one page
Cmd-PgDnCtrl-PgDnScroll down one page

DIRS tab – browsing directories

  • Type random text into the top textbox to filter via regex.
  • Press the <- / -> buttons to go forward or backward in your directory history.
  • Press the .. button to go up one directory.
  • Press the “cd” button to change to the previously-active shell tab and CD to that directory.
  • Click directories to navigate into them. You can click anywhere on the line (except the selection box), you don’t have to click right on the directory name.
  • Select directories & files via the selection boxes, and then press the “Copy” or “Edit” buttons (which are only displayed once you’ve selected some files.)
    • The “Copy” button copies the selected filenames to the clipboard.
    • The “Edit” button edits the selected files in a local editor.
  • Click the Size / Time / Name buttons to change how the listing is sorted.
  • Click any component of the diplayed directory (next to the “cd” button) to change to that directory. E.g. for /home/you/some/directory, click on “you” to change to /home/you.
  • Press Cmd/Ctrl-D/F/O to show or hide Directories, Files, and dOtfiles (e.g. .huckshrc). If you’re hiding “dotfiles”, all directory entries starting with a . will be hidden, whether they’re directories or files.

Text box filtering

  • As mentioned above, type text into the box to filter via the given regex.
  • If you filter down to where there’s only a single directory that matches your regex (even if several other non-directories also match), press “/” to navigate into that directory.
  • If you press “/” with no text, this navigates directly to the root directory.

“Navigation mode”

Press Cmd-M (Linux: Ctrl-M) to enter navigation mode. This displays a new “Nav” column in the directory listing, with various automatically generated shortcuts for each directory. Press the given letter to navigate into that directory.

Press ESC or Cmd-M (Linux: Ctrl-M) again to exit navigation mode. Leave the DIRS tab and then returning also disables navigation mode.

Navigation mode shows only directories and hides all non-directories.

DIRS tab Hotkeys

macOSLinuxMeaning
Cmd-1Ctrl-1Switch to the DIRS tab
ESCESCTurn off Navigation mode, or clear the current regex
Cmd-MCtrl-MEnter or leave Navigation mode
Cmd-RCtrl-RRefresh the directory listing
Cmd-DCtrl-DShow or hide directories
Cmd-FCtrl-FShow or hide files
Cmd-OCtrl-OShow or hide “dotfiles” (.*)
Cmd-U (see warning)
Cmd-Up
Ctrl-U
Ctrl-Up
Go up one directory
Cmd-Left
Cmd-Down
Ctrl-Left
Ctrl-Down
Go backwards in history
Cmd-RightCtrl-RightGo forwards in history
Enter
Cmd-Enter
Enter
Ctrl-Enter
Switch to the current shell tab and CD to the current directory
Cmd-HomeCtrl-HomeScroll to top
Cmd-EndCtrl-EndScroll to end
Cmd-PgUpCtrl-PgUpPage up
Cmd-PgDnCtrl-PgDnPage down
Cmd-Shift-CCtrl-Shift-CCopy the current directory name to the system clipboard
Cmd-Shift-VCtrl-Shift-VCD to the directory in the system clipboard
Cmd-Shift-Opt-CCtrl-Shift-Alt-CCopy filenames of selected items to the system clipboard
Cmd-Shift-NCtrl-Shift-NToggle name sort
Cmd-Shift-TCtrl-Shift-TToggle time sort
Cmd-Shift-SCtrl-Shift-SToggle size sort
Cmd-Shift-ACtrl-Shift-AToggle on/off all file selections
Cmd-Shift-ECtrl-Shift-EEdit selected files
DIRS tab Hotkeys

The regexp textbox has several of its own hotkeys, not mentioned here.

HIST tab – viewing historical directory usage

The HIST tab lists all the directories you’ve ever used, in any session, where “used” means:

  • Pressed “Enter” on it in the DIRS tab to CD to that directory in a shell tab
  • CDed to it in a shell tab (that is, it was the shell’s $PWD at the end of a command)

It’s updated immediately in all clients, so if you use a directory in one client it should immediately show up in the HIST tab of all clients. (This is most obvious when you sort by “last visited”.)

HIST tab usage

  • Press enter to show the selected directory in the DIRS tab
  • Click on a displayed directory to open it in the DIRS tab
  • Type random text into the top textbox to filter the directories via regex
  • Click the Uses / Dir / Last visit buttons to change the sorting

HIST tab hotkeys

macOSLinuxMeaning
Cmd-2Ctrl-2Switch to the HIST tab
EnterEnterOpen the selected directory in the DIRS tab
ESCESCClear the current regex
Cmd-Shift-DCtrl-Shift-DToggle sort by directory name
Cmd-Shift-LCtrl-Shift-LToggle sort by last visit
Cmd-Shift-UCtrl-Shift-UToggle sort by uses
Cmd-HomeCtrl-HomeScroll to top
Cmd-EndCtrl-EndScroll to end
Cmd-PgUpCtrl-PgUpPage up
Cmd-PgDnCtrl-PgDnPage down
Cmd-UpCtrl-UpMove selection bar up
Cmd-DownCtrl-DownMove selection bar down
Cmd-Shift-CCtrl-Shift-CCopy the selected directory to the system clipboard
Cmd-Shift-VCtrl-Shift-VOpen the directory in the system clipboard in the DIRS tab
HIST tab hotkeys

Tip: Note that Enter here opens the selected directory in the DIRS tab, and Enter in the DIRS tab will switch to the current shell tab and CD to that directory. So from the HIST tab, press Enter twice to switch to the current shell tab & CD to that directory.