📂 nav 📂

❯ The interactive and stylish replacement for ls & cd!

Ever tried to find that one config file hidden deep in your directory tree? Or maybe you just want to quickly jump to a directory and inspect some files on the way?
✨ nav is here to help! ✨
Written in Kotlin/Native, nav provides a modern and intuitive terminal UI to navigate your filesystem.

➡️ Use arrow keys to navigate everywhere
⌨️ Type to filter entries, press Tab to autocomplete
✏️ Instantly edit files with your favorite editor on the fly
✅ Press Enter to move your shell to the current directory
🔧 Configure everything to your liking
⭐ Define custom macros for even more powerful workflows
📈 Create files and directories or run commands everywhere

🚀 Installation

1. Install nav

Select your operating system

Linux

Install with any of the following package managers:

Distribution	Repository	Instructions
Arch Linux	AUR	`pacman -S nav-cli` `yay -S nav-cli`
NixOS	Nixpkgs	`nix-shell -p nav`
Debian, Ubuntu, etc.	nav_amd64.deb nav_arm64.deb	`dpkg -i ...`

Or install (or update) nav with the installer script:

curl -sS https://raw.githubusercontent.com/Jojo4GH/nav/master/install/install.sh | sh

Or manually download the latest release.

Windows

On Windows, you can use scoop to install nav:

scoop bucket add JojoIV "https://github.com/Jojo4GH/scoop-JojoIV"
scoop install nav

Or without adding the bucket:

scoop install "https://raw.githubusercontent.com/Jojo4GH/scoop-JojoIV/master/bucket/nav.json"

2. Set up your shell

Configure your shell to initialize nav. This is required for the cd part of nav's functionality.

Bash

Add the following to the end of ~/.bashrc:

eval "$(nav --init bash)"

Zsh

Add the following to the end of ~/.zshrc:

eval "$(nav --init zsh)"

Powershell

Add one of the following to the end of your PowerShell configuration (find it by running $PROFILE):

Invoke-Expression (& nav --init powershell | Out-String)

Invoke-Expression (& nav --init pwsh | Out-String)

NixOS

Bash:

programs.bash.shellInit = "eval \"$(nav --init bash)\"";

Zsh:

programs.zsh.shellInit = "eval \"$(nav --init zsh)\"";

Or with home-manager:

home-manager.users.user.programs = {
    bash = {
        enable = true;
        bashrcExtra = "eval \"$(nav --init bash)\"";
    };
    zsh = {
        inherit (config.programs.zsh) enable;
        initExtra = "eval \"$(nav --init zsh)\"";
    };
};

Shell completion

Basic support for shell completion is currently available for Bash and Zsh through the --completion option. It can also be used in combination with --init:

eval "$(nav --init bash --completion bash)"

eval "$(nav --init zsh --completion zsh)"

3. Basic Usage

The default keybinds are:

Key	Description	Configuration
`↑`/`↓`	Move cursor up/down	`keys.cursor.up`, `keys.cursor.down`
`Home`/`End`	Move cursor to first/last	`keys.cursor.home`, `keys.cursor.end`
`←`	Go up one directory	`keys.nav.up`
`→`	Go into directory / Open file	`keys.nav.into`, `keys.nav.open`
`Enter`	Exit and cd to directory / Submit	`keys.submit`
`Esc`	Exit (don't cd) / Cancel	`keys.cancel`
`ctrl`+`C`	Exit	-
`PageUp`/`PageDown`	Open menu / Move menu cursor up/down	`keys.menu.up`, `keys.menu.down`
`Tab`	Autocomplete	`keys.filter.autocomplete`, `autocomplete` (see below)
`Esc`	Clear filter or input	`keys.filter.clear`
`...`	Type filter or input	-
`...`	Any macro key	See macros
`ctrl` + `...`	Any quick macro mode key	See macros

All available keybinds are (by default) also shown at the bottom in nav.

🔧 Configuration

To create or edit the config file you can use the --edit-config command line option. Config files can be written in either YAML (recommended) or TOML format (but not both). The default locations for the file are ~/.config/nav.yaml, ~/.config/nav.yml or ~/.config/nav.toml. If you intend to define macros, please use the YAML format. You can change this by setting the NAV_CONFIG environment variable:

Linux

export NAV_CONFIG=~/some/other/path/nav.yaml

Powershell

$ENV:NAV_CONFIG = "$HOME\some\other\path\nav.yaml"

You can also use the --config command line option to explicitly specify a config file.

The default configuration looks as follows:

General

YAML

# If not specified, uses the first that exists of the following:
# $EDITOR, $VISUAL, nano, nvim, vim, vi, code, notepad
# You can also use the --editor command line option to override this
editor: null

suppressInitCheck: false
clearOnExit: true
autoCheckForUpdates: true

limitToTerminalHeight: true
maxVisibleEntries: 40 # Set to 0 for unlimited entries
maxVisiblePathElements: 6
showHiddenEntries: true
hideHints: false

# Used to distinguish escape sequences on Linux terminals
inputTimeoutMillis: 4 # Set to 0 for no timeout

# Which columns to show for each entry and how to order them
shownColumns:
- Permissions       # Permissions of the entry in unix style
# - HardLinkCount   # Number of hard links to the entry (not shown by default)
# - UserName        # Name of the user owning the entry (not shown by default)
# - GroupName       # Name of the group owning the entry (not shown by default)
- EntrySize         # Size of the file
- LastModified      # Time of last modification

TOML

# If not specified, uses the first that exists of the following:
# $EDITOR, $VISUAL, nano, nvim, vim, vi, code, notepad
# You can also use the --editor command line option to override this
editor = "" # Default: null

suppressInitCheck = false
clearOnExit = true
autoCheckForUpdates = true

limitToTerminalHeight = true
maxVisibleEntries = 20 # Set to 0 for unlimited entries
maxVisiblePathElements = 6
showHiddenEntries = true
hideHints = false

# Used to distinguish escape sequences on Linux terminals
inputTimeoutMillis = 4 # Set to 0 for no timeout

# Which columns to show for each entry and how to order them
shownColumns = [
    "Permissions",      # Permissions of the entry in unix style
    # "HardLinkCount",  # Number of hard links to the entry (not shown by default)
    # "UserName",       # Name of the user owning the entry (not shown by default)
    # "GroupName",      # Name of the group owning the entry (not shown by default)
    "EntrySize",        # Size of the file
    "LastModified",     # Time of last modification
]

Controls

For valid key names see web keyboard event values.

YAML

keys:
  submit: Enter
  cancel: Escape
  
  cursor:
    up: ArrowUp
    down: ArrowDown
    home: Home
    end: End
  
  nav:
    up: ArrowLeft
    into: ArrowRight
    open: ArrowRight
  
  menu:
    up: PageUp
    down: PageDown
  
  filter:
    autocomplete: Tab
    clear: Escape

autocomplete:
  # Controls the behavior of the auto complete feature
  # - CommonPrefixCycle: Auto completes the largest common prefix and cycles through all entries
  # - CommonPrefixStop: Auto completes the largest common prefix and stops
  style: CommonPrefixCycle
  # Controls auto navigation on completion
  # - None: Do not auto navigate
  # - OnSingleAfterCompletion: Auto completes the entry and on second action navigates
  # - OnSingle: Auto completes the entry and navigates immediately (not recommended)
  autoNavigation: OnSingleAfterCompletion

TOML

[keys]

submit = "Enter"
cancel = "Escape"

cursor.up = "ArrowUp"
cursor.down = "ArrowDown"
cursor.home = "Home"
cursor.end = "End"

nav.up = "ArrowLeft"
nav.into = "ArrowRight"
nav.open = "ArrowRight"

menu.up = "PageUp"
menu.down = "PageDown"

filter.autocomplete = "Tab"
filter.clear = "Escape"

[autocomplete]

# Controls the behavior of the auto complete feature
# - "CommonPrefixCycle": Auto completes the largest common prefix and cycles through all entries
# - "CommonPrefixStop": Auto completes the largest common prefix and stops
style = "CommonPrefixCycle"
# Controls auto navigation on completion
# - "None": Do not auto navigate
# - "OnSingleAfterCompletion": Auto completes the entry and on second action navigates
# - "OnSingle": Auto completes the entry and navigates immediately (not recommended)
autoNavigation = "OnSingleAfterCompletion"

Appearance

YAML

colors:
  # Possible values for themes are:
  # - Retro (default theme)
  # - Monochrome (default simpleTheme)
  # - SimpleColor
  # - Random
  # - Sunset
  # - Xmas
  # - Hub
  # - Ice
  # - Darcula
  # - AtomOneDark
  theme: Retro
  simpleTheme: Monochrome   # Used for terminals with less color capabilities (see: accessibility.simpleColors)

  # The following colors can also be explicitly set (default: theme/simpleTheme colors):
  path: null
  filter: null
  filterMarker: null
  keyHints: null
  keyHintLabels: null
  genericElements: null
  
  permissionRead: null
  permissionWrite: null
  permissionExecute: null
  permissionHeader: null
  hardlinkCount: null
  hardlinkCountHeader: null
  user: null
  userHeader: null
  group: null
  groupHeader: null
  entrySize: null
  entrySizeHeader: null
  modificationTime: null
  modificationTimeHeader: null
  
  directory: null
  file: null
  link: null
  nameHeader: null
  nameDecorations: null

modificationTime:     # Configure how the modification time is rendered
  minimumBrightness: 0.4
  halfBrightnessAtHours: 12.0

accessibility:
  decorations: null   # Whether to use the simple color theme (default: auto)
  simpleColors: null  # Whether to show decorations (default: auto)

TOML

[colors]

# Possible values for themes are:
# - "Retro" (default theme)
# - "Monochrome" (default simpleTheme)
# - "SimpleColor"
# - "Random"
# - "Sunset"
# - "Xmas"
# - "Hub"
# - "Ice"
# - "Darcula"
# - "AtomOneDark"
theme = "Retro"
simpleTheme = "Monochrome"  # Used for terminals with less color capabilities (see: accessibility.simpleColors)

# The following colors can also be explicitly set (default: theme/simpleTheme colors):
path = "#FFFFFF"
filter = "#FFFFFF"
filterMarker = "#FFFFFF"
keyHints = "#FFFFFF"
keyHintLabels = "#FFFFFF"
genericElements = "#FFFFFF"

permissionRead = "#FFFFFF"
permissionWrite = "#FFFFFF"
permissionExecute = "#FFFFFF"
permissionHeader = "#FFFFFF"
hardlinkCount = "#FFFFFF"
hardlinkCountHeader = "#FFFFFF"
user = "#FFFFFF"
userHeader = "#FFFFFF"
group = "#FFFFFF"
groupHeader = "#FFFFFF"
entrySize = "#FFFFFF"
entrySizeHeader = "#FFFFFF"
modificationTime = "#FFFFFF"
modificationTimeHeader = "#FFFFFF"

directory = "#FFFFFF"
file = "#FFFFFF"
link = "#FFFFFF"
nameHeader = "#FFFFFF"
nameDecoration = "#FFFFFF"

[modificationTime]    # Configure how the modification time is rendered

minimumBrightness = 0.4
halfBrightnessAtHours = 12.0

[accessibility]

simpleColors = false  # Whether to use the simple color theme (default: auto)
decorations = false   # Whether to show decorations (default: auto)

⭐ Macros

Note

Macros are currently an experimental feature. They may change in future releases with no guarantees of compatibility. Please report any issues. For the more limited but stable variant, see Entry Macros.

With macros, you can define small scripts that can interact with nav in various ways (see Examples). They can also overwrite existing functionality to customize nav to your workflow.

Macros can be accessed with their key or through the menu (default PageDown). They can also quickly be triggered by tapping ctrl together with or followed by their quickModeKey.

Examples

There are also more examples in the default macro section.

YAML

macros:

# Open the current directory in code (Trigger: ctrl+ArrowUp)
- description: open in code
  key: ctrl+ArrowUp
  hideKey: true
  run:
  - command: code "{{directory}}"

# Open the current entry in code (Trigger: ctrl+ArrowRight)
- description: open {{entryName}} in code
  quickModeKey: ArrowRight
  condition:
    notEmpty: "{{entryName}}"                       # Only if an entry is selected
  run:
  - command: code "{{entryName}}"

# Overwrite the default behavior of ArrowRight to open PDF files in the browser instead of the editor
- description: open pdf in browser
  key: ArrowRight
  condition:
    all:
    - equal: [ "{{entryType}}", "file" ]            # Must be a file
    - match: ".*\\.pdf"                             # Check if it ends with .pdf
      in: "{{entryName}}"
      ignoreCase: true
  run:
  - command: chromium "{{entryPath}}"

# Navigate to the home directory if not already there (Trigger: ctrl+Home)
- description: home
  quickModeKey: Home
  condition:
    notEqual: [ "{{directory}}", "{{env:HOME}}" ]   # or "{{env:USERPROFILE}}" on Windows
  run:
  - set:
      directory: "{{env:HOME}}"                     # or "{{env:USERPROFILE}}" on Windows

# Create a hardlink of the current file (Trigger: Select from menu)
- description: Create hardlink of {{entryName}}
  menuOrder: 10
  condition:
    equal: [ "{{entryType}}", "file" ]              # Only for files
  run:
  - prompt: "Link path:"
    format: ".+"                                    # Not empty
    default: "/data/temp/"                          # Pre-fill with /data/temp/
    resultTo: linkPath
  - command: mkdir -p "$(dirname '{{linkPath}}')"   # Create parent directories
  - command: ln "{{entryPath}}" "{{linkPath}}"      # Create the hardlink

Definition

Currently, only the YAML configuration can be used to define macros:

YAML

# Defines a list of macros
# Macros are shown in the following places if they are enabled and their condition is met:
# - In key hints, if a 'key' is set and not 'hideKey'
# - In quick macro mode, if a 'quickModeKey' is set and not 'hideQuickModeKey'
# - In the menu, if a 'menuOrder' is set
macros:

- # Unique id of the macro used for referencing it (optional, default: null)
  id: null
  
  # Whether the macro is enabled (optional, default: true)
  enabled: true
  
  # Description of the macro shown in nav (supports templates, required if not hidden, default: "")
  description: ""
  
  # Style of the macro key hints, menu entry and dialogs (optional, default: null)
  # This can one of the keys of the 'colors' section (e.g. "directory") or a hex color 
  style: null

  # Key used to trigger the macro in normal mode (optional, default: null)
  # For valid key names see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
  key: null
  
  # Whether to hide the hint for the normal mode key (optional, default: false)
  hideKey: false
  
  # Key used to trigger the macro in quick macro mode (optional, default: null)
  # For valid key names see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
  quickModeKey: null
  
  # Whether to hide the hint for the quick mode key (optional, default: false)
  hideQuickModeKey: false
  
  # The order in which the macro appears in the menu (optional, default: null)
  # If null, the macro does not appear in the menu.
  # Lower numbers appear first.
  menuOrder: null
  
  # The condition that must be met for the macro to be available (optional, default: null, see "Conditions" below)
  # If no condition is specified, the macro is always available.
  condition:
    # ...
  
  # The actions to run when the macro is triggered (optional, default: [])
  # See "Actions" below
  run:
  - # action 1
  - # action 2
  - # ...

Conditions

YAML

# Possible conditions are:

  # True if any child condition is true (similar to logical OR)
- any:
  - # child condition 1
  - # child condition 2
  - # ...
  
  # True if all child conditions are true (similar to logical AND)
- all:
  - # child condition 1
  - # child condition 2
  - # ...
  
  # True if the child condition is false (similar to logical NOT)
- not:
    # child condition
  
  # True if all values are equal (the values support templates)
- equal: [ "value 1", "value 2", ... ]
  ignoreCase: false       # Whether to ignore case when comparing (optional, default: false)

  # True if any values are not equal (the values support templates)
- notEqual: [ "value 1", "value 2", ... ]
  ignoreCase: false       # Whether to ignore case when comparing (optional, default: false)

  # True if the entire value matches the given regular expression
- match: "..."            # A regex pattern (required)
  in: "..."               # (supports templates, required)
  ignoreCase: false       # Whether to ignore case when matching (optional, default: false)

  # True if the value is empty
- empty: "..."            # (supports templates, required)

  # True if the value is not empty
- notEmpty: "..."         # (supports templates, required)

  # True if the value contains only whitespace 
- blank: "..."            # (supports templates, required)

  # True if the value does not contain only whitespace
- notBlank: "..."         # (supports templates, required)

  # True if the value is a path to file or directory
- exists: "..."           # (supports templates, required)

  # True if the value is not a path to file or directory
- notExists: "..."        # (supports templates, required)

  # True if the value is a path to a directory
- isDirectory: "..."      # (supports templates, required)

  # True if the value is not a path to a directory
- notIsDirectory: "..."   # (supports templates, required)
  
  # True if the value is a path to a file
- isFile: "..."           # (supports templates, required)

  # True if the value is not a path to a file
- notIsFile: "..."        # (supports templates, required)

Actions

YAML

# Possible actions are:

  # If the condition is true, run the 'then' actions, otherwise run the 'else' actions.
- if:                         # A condition (required, see "Conditions")
    # ...
  then:                       # Array of actions (optional, default: [])
  - # then action 1
  - # then action 2
  - # ...
  else:                       # Array of actions (optional, default: [])
  - # else action 1
  - # else action 2
  - # ...

  # Switches over the given values and runs the corresponding actions.
  # If multiple cases match, the first matching case is executed.
- when: "..."               # The value to compare (supports templates, required)
  ignoreCase: false         # Whether to ignore case when matching (optional, default: false)
  is:                       # A map of cases (optional, default: {})
  # "case1":                # Array of actions (key supports templates, default: [])
  # - # case1 action 1
  # - # case1 action 2
  # - # ...
  # "case2":                # Array of actions (key supports templates, default: [])
  # - # case2 action 1
  # - # case2 action 2
  # - # ...
  # ...
  else:                     # Array of actions (optional, default: [])
  - # else action 1
  - # else action 2
  - # ...


  # Prints the given message.
- print: "..."                # (supports templates, required)
  style: null                 # (optional, default: null, valid values: ["info", "success", "warning", "error"])
  debug: false                # Whether to only print in debug mode (optional, default: false)

  # Sets the given properties/variables to the given values.
  # The properties must be mutable.
  # No property/variable that is set can appear in templates on the value side in the same set action
  # (use multiple set actions instead).
- set:
    # name1: "value 1"        # (value supports templates)
    # name2: "value 2"        # ^^
    # ...

  # Runs the sub macro with the given id.
- macro: "..."                # (required)
  ignoreCondition: false      # Whether to ignore the macro's condition (optional, default: false)
  # A map of parameters to pass to the sub macro (the values support templates, optional, default: null)
  # If this is null, then all currently set variables are passed to the sub macro.
  # All set parameters are available in the sub macro as variables.
  # Modifying those variables in the sub macro does not affect the parent macro.
  parameters: null
  # A map of values to capture from the sub macro (the values support templates, optional, default: null)
  # The keys are the names of properties/variables to assign in the parent macro
  # The values are evaluated in the sub macro's context.
  capture: null
  # Whether to continue executing the current macro if the sub macro explicitly returns (optional, default: true)
  continueOnReturn: true

  # Runs the given command.
  # Commands are run in the directory where nav currently is (see {{directory}} placeholder).
- command: "..."              # (supports templates, required)
  exitCodeTo: "exitCode"      # The variable/property to store the exit code in (optional, default: "exitCode")
  # The variable/property to store the standard output in (optional, default: null)
  # If this is null, the output gets printed to the terminal.
  outputTo: null
  trimTrailingNewline: true   # Whether to trim a single trailing newline from the output (optional, default: true)
  # The variable/property to store the standard error in (optional, default: null)
  # If this is null, the error output gets printed to the terminal.
  errorTo: null

  # Opens the given file in the editor (see 'editor' configuration or '--editor' command line option).
- open: "..."                 # (supports templates, required)
  exitCodeTo: "exitCode"      # The variable/property to store the editor's exit code in (optional, default: "exitCode")

  # Writes the given content to the given file.
  # If the file does not exist, it is created.
- writeFile: "..."            # (supports templates, required)
  content: null               # The content to write to the file (optional, default: null)
  append: false               # Whether to append to the file (optional, default: false)
  overwrite: false            # Whether to overwrite the file if it already exists (optional, default: false)
  silent: false               # Whether to omit warnings if the file could not be written (optional, default: false)

  # Creates the given directory.
- createDirectory: "..."      # (supports templates, required)
  createParents: true         # Whether to create parent directories if they do not exist (optional, default: true)
  silent: false               # Whether to omit warnings if the directory could not be created (optional, default: false)

  # Moves the given file or directory to the given destination.
  # Can be used to rename files or directories.
- move: "..."                 # (supports templates, required)
  to: "..."                   # (supports templates, required)
  createParents: true         # Whether to create parent directories if they do not exist (optional, default: true)
  overwrite: false            # Whether to overwrite the destination if it already exists (optional, default: false)
  silent: false               # Whether to omit warnings if the operation fails (optional, default: false)

  # Deletes the given file or directory.
- delete: "..."               # (supports templates, required)
  recursive: false            # Whether to delete the directory recursively (optional, default: false)
  silent: false               # Whether to omit warnings if the operation fails (optional, default: false)

  # Returns the children of the given directory.
  # The children are separated by newlines.
- childrenOf: "..."           # (supports templates, required)
  fullPath: false             # Whether to return the full paths of the children instead of their names (optional, default: false)
  resultTo: "result"          # The variable/property to store the result in (optional, default: "result")

  # Prompts the user for input.
  # Not both 'format' and 'choices' can be specified at the same time.
  # If choices are specified, the user must select one of the choices.
  # Otherwise, the user must enter a value matching the format (if specified).
- prompt: "..."               # The message to show (supports templates, required)
  format: null                # A regex pattern the entire input must match (optional, default: null)
  choices: []                 # A list of choices (values support templates, optional, default: [])
  default: null               # The default value (supports templates, optional, default: null)
  hideMainTable: false        # Whether to hide the main table while the prompt is shown (optional, default: false)
  resultTo: "result"          # The variable/property to store the result in (optional, default: "result")
  onChoice:                   # A map of actions to run when a choice is selected (optional, default: {})
  # "choice1":                # Array of actions (key supports templates, default: [])
  # - # choice1 action 1
  # - # choice1 action 2
  # - # ...
  # "choice2":                # Array of actions (key supports templates, default: [])
  # - # choice2 action 1
  # - # choice1 action 2
  # - # ...
  # ...

  # Matches the entire value against the given regex pattern.
  # If it matches, the capturing groups are stored in the given properties/variables.
  # The first capturing group is stored in the first property/variable, the second in the second, etc.
- match: "..."                # A regex pattern (required)
  in: "..."                   # (supports templates, required)
  ignoreCase: false           # Whether to ignore case when matching (optional, default: false)
  groupsTo: []                # A list of properties/variables to store the capturing groups in (optional, default: [])

  # Explicitly returns from the current macro (but not from nav) if the value is true.
  # Any action in this macro after this action is not executed.
  # Actions in possible parent macros may still be executed.
- return: true                # (required)

  # Immediately exits nav if the value is true.
  # If no directory is specified, nav exits at the working directory it was started from.
- exit: true                  # (required)
  at: null                    # The directory to exit at (supports templates, optional, default: null)

Properties, Variables & Template Strings

Many strings in macros support templates with placeholders that get replaced with their respective values when the macro is run. Placeholders are specified by surrounding the name with double curly braces, e.g. {{myVariable}}. They can appear multiple times in a string and anywhere inside the string. Placeholders are replaced once (no recursive replacement). Currently, there is no escaping mechanism for placeholders.

There are several built-in properties, some of which can be modified to affect nav's behavior:

Name	Mutable	Description
`workingDirectory`	❌	The working directory of nav's process
`startingDirectory`	❌	The directory where nav was started (i.e. the directory specified in the command line)
`shell`	❌	The shell that nav currently uses (see `--shell`)
`separator`	✅	The separator of path elements of the current platform (e.g. `/` or `\`)
`debugMode`	❌	Whether nav is currently running in debug mode
`directory`	✅	The current directory inside nav
`entryPath`	❌	The path of the currently highlighted entry or empty if no entry is highlighted.
`entryName`	❌	The name of the currently highlighted entry or empty if no entry is highlighted.
`entryType`	❌	The type of the currently highlighted entry. Possible values are `directory`, `file`, `link`, `unknown` and empty.
`entryCursorPosition`	✅	The index of the currently highlighted entry relative to all filtered entries
`menuCursorPosition`	✅	The index of the currently highlighted menu item
`filter`	✅	The current filter string or empty if no filter is set
`filteredEntriesCount`	❌	The number of entries currently matching the filter
`command`	✅	The currently typed command or empty if no command is typed

Any environment variable can be accessed and modified as well by using the prefix env:, e.g. {{env:HOME}}.

Additionally, macros can define their own mutable variables that can be used in template strings (see set macro action).

Macro Merging & Default Macros

Macros with the same id are merged. Options specified in the later macro overwrite those in the earlier one.

Nav comes with a number of macros that are available without additional configuration. Users can change their behavior or disable them by using macro merging as described above:

# Change the key of the default rename macro
- id: "nav:rename"
  key: F6

# Disable the default deletion macro
- id: "nav:delete"
  enabled: false

Current Default Macros

YAML

- id: "nav:newFile"
  description: "new file: {{filter}}"
  style: "file"
  menuOrder: 200
  condition:
    all:
    - notBlank: "{{filter}}"
    - notExists: "{{filter}}"
  run:
  - writeFile: "{{filter}}"
  - set:
      "filter": ""

- id: "nav:newDirectory"
  description: "new directory: {{filter}}"
  style: "directory"
  menuOrder: 210
  condition:
    all:
    - notBlank: "{{filter}}"
    - notExists: "{{filter}}"
  run:
  - createDirectory: "{{filter}}"
  - set:
      "filter": ""

- id: "nav:rename"
  description: "rename {{entryName}}"
  menuOrder: 250
  condition:
    notEmpty: "{{entryName}}"
  run:
  - prompt: "New name:"
    format: "[^:*?\"<>|]+"
    default: "{{entryName}}"
    resultTo: "nav:rename:newName"
  - if:
      exists: "{{nav:rename:newName}}"
    then:
    - prompt: |-
        {{nav:rename:newName}} already exists.
        Do you want to overwrite it?
      default: "No"
      choices:
      - "No"
      - "Yes"
      onChoice:
        "No":
        - return: true
    - move: "{{entryPath}}"
      to: "{{nav:rename:newName}}"
      overwrite: true
    else:
    - move: "{{entryPath}}"
      to: "{{nav:rename:newName}}"

- id: "nav:delete"
  description: "delete {{entryName}}"
  key: "Delete"
  menuOrder: 300
  condition:
    notEmpty: "{{entryName}}"
  run:
  - if:
      isDirectory: "{{entryPath}}"
    then:
    - childrenOf: "{{entryPath}}"
      resultTo: "nav:delete:children"
    - if:
        notEmpty: "{{nav:delete:children}}"
      then:
      - prompt: |-
          The directory {{entryName}} is not empty.
          Do you want to delete it recursively?
        default: "No"
        choices:
        - "No"
        - "Yes"
        onChoice:
          "No":
          - return: true
      - delete: "{{entryPath}}"
        recursive: true
      else:
      - delete: "{{entryPath}}"
    else:
    - delete: "{{entryPath}}"

Entry Macros

Note

Entry macros will be superseded by Macros in the future.

You can define custom macros that work with entries (e.g. directories, files) in the configuration file as follows:

YAML

entryMacros:
- # The description displayed (required) (see placeholders)
  description: ...
  # The conditions for the macro to be available (defaults to false)
  onFile: false
  onDirectory: false
  onSymbolicLink: false
  # The command to run (required) (see placeholders)
  command: ...
  # What to do after the command was executed. Possible values are:
  # - DoNothing: Do nothing
  # - ExitAtCurrentDirectory: Exit at the current directory
  # - ExitAtInitialDirectory: Exit at the initial directory
  afterCommand: ...            # Defaults to DoNothing
  afterSuccessfulCommand: ...  # Defaults to value of afterCommand
  afterFailedCommand: ...      # Defaults to value of afterCommand
  # The key to trigger the macro or null for no quick macro (defaults to null)
  quickMacroKey: ...

TOML

[[entryMacros]]
# The description displayed (required) (see placeholders)
description = "..."
# The conditions for the macro to be available (defaults to false)
onFile = false
onDirectory = false
onSymbolicLink = false
# The command to run (required) (see placeholders)
command = "..."
# What to do after the command was executed. Possible values are:
# - "DoNothing": Do nothing
# - "ExitAtCurrentDirectory": Exit at the current directory
# - "ExitAtInitialDirectory": Exit at the initial directory
afterCommand = "..."            # Defaults to "DoNothing"
afterSuccessfulCommand = "..."  # Defaults to value of afterCommand
afterFailedCommand = "..."      # Defaults to value of afterCommand
# The key to trigger the macro or null for no quick macro (defaults to null)
quickMacroKey = "..."

There are several placeholders available for description and command:

{initialDir}: The initial directory where nav was started
{dir}: The current directory inside nav
{entryPath}: The path of the currently highlighted entry
{entryName}: The name of the currently highlighted entry
{filter}: The current filter string or empty if no filter is set

Macros are available in the menu (default PageDown). They can also quickly be triggered by tapping ctrl together with or followed by the quickMacroKey.

Examples:

YAML

entryMacros:

- # An alternative editor macro
  description: open {entryName} in code
  command: code '{entryPath}'
  afterSuccessfulCommand: ExitAtCurrentDirectory
  onFile: true
  onDirectory: true
  quickMacroKey: ArrowRight
  
- # Same as above, but waits for the editor to close before returning again to nav
  description: open {entryName} in code and wait
  command: code --wait '{entryPath}'
  onFile: true
  onDirectory: true
  quickMacroKey: shift+ArrowRight
  
- # A macro for deleting directories recursively
  description: delete {entryName} recursively
  command: rm -rf '{entryPath}'
  onDirectory: true
  quickMacroKey: Delete
  
- # A macro for printing the full path of the entry
  description: print full path
  command: echo '{entryPath}'
  onFile: true
  onDirectory: true
  onSymbolicLink: true

TOML

# An alternative editor macro
[[entryMacros]]
description = "open {entryName} in code"
command = "code '{entryPath}'"
afterSuccessfulCommand = "ExitAtCurrentDirectory"
onFile = true
onDirectory = true
quickMacroKey = "ArrowRight"

# Same as above, but waits for the editor to close before returning again to nav
[[entryMacros]]
description = "open {entryName} in code and wait"
command = "code --wait '{entryPath}'"
onFile = true
onDirectory = true
quickMacroKey = "shift+ArrowRight"

# A macro for deleting directories recursively
[[entryMacros]]
description = "delete {entryName} recursively"
command = "rm -rf '{entryPath}'"
onDirectory = true
quickMacroKey = "Delete"

# A macro for printing the full path of the entry
[[entryMacros]]
description = "print full path"
command = "echo '{entryPath}'"
onFile = true
onDirectory = true
onSymbolicLink = true

Known Issues

On Windows some symbolic link destinations can not be resolved correctly.
On Windows special characters in paths may lead invalid file information being returned or errors (#22, #24).
This can be fixed by enabling Settings -> Language & region -> Administrative language settings -> Change system locale... -> Use Unicode UTF-8 for worldwide language support

❤️ Powered by

UI: Mordant
CLI: Clikt
Commands: Kommand
Config file: kotlinx.serialization, ktoml, kaml
Kotlin/Native

Name		Name	Last commit message	Last commit date
.github		.github
app		app
config/detekt		config/detekt
framework		framework
gradle/wrapper		gradle/wrapper
install		install
media		media
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Navigation Menu

Repository files navigation

📂 nav 📂

Contents

🚀 Installation

1. Install nav

2. Set up your shell

3. Basic Usage

🔧 Configuration

General

Controls

Appearance

⭐ Macros

Examples

Definition

Conditions

Actions

Properties, Variables & Template Strings

Macro Merging & Default Macros

Current Default Macros

Entry Macros

Known Issues

❤️ Powered by

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

📂 nav 📂

Contents

🚀 Installation

1. Install nav

2. Set up your shell

3. Basic Usage

🔧 Configuration

General

Controls

Appearance

⭐ Macros

Examples

Definition

Conditions

Actions

Properties, Variables & Template Strings

Macro Merging & Default Macros

Current Default Macros

Entry Macros

Known Issues

❤️ Powered by

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages