{"id":26847732,"url":"https://github.com/littlewalter/up","last_synced_at":"2026-05-05T09:33:20.237Z","repository":{"id":283925492,"uuid":"953303032","full_name":"LittleWalter/up","owner":"LittleWalter","description":"An alternative way to quickly change directories up the tree! Navigate to ancestor directories by count and directory name with tab completion.","archived":false,"fork":false,"pushed_at":"2025-03-30T11:41:29.000Z","size":853,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T12:27:32.085Z","etag":null,"topics":["bash","bash-configuration","bash-scripting","cd","change-dir","change-directory","cli","command-line","filesystem","filesystem-utils","navigation","shell","tab-completion","terminal","zsh","zsh-configuration"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LittleWalter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-23T03:13:57.000Z","updated_at":"2025-03-30T11:41:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb2ac9d7-c514-41e7-8900-ac7dae97eaaa","html_url":"https://github.com/LittleWalter/up","commit_stats":null,"previous_names":["littlewalter/up"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LittleWalter%2Fup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LittleWalter%2Fup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LittleWalter%2Fup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LittleWalter%2Fup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LittleWalter","download_url":"https://codeload.github.com/LittleWalter/up/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246374728,"owners_count":20766947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bash-configuration","bash-scripting","cd","change-dir","change-directory","cli","command-line","filesystem","filesystem-utils","navigation","shell","tab-completion","terminal","zsh","zsh-configuration"],"created_at":"2025-03-30T20:23:37.921Z","updated_at":"2026-05-05T09:33:20.217Z","avatar_url":"https://github.com/LittleWalter.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003e\n    \u003cimg src=\"assets/up_folder_icon.svg\" alt=\"Icon representing directory navigation with up script\" width=\"35px\"\u003e\n    Navigate \u003ccode\u003eup\u003c/code\u003e the Directory Tree with Ease | Bash \u0026 Zsh Navigation Script\n\u003c/h1\u003e\n\n`up` is a Bash and Zsh script that takes the hassle out of navigating parent and ancestor directories. Effortlessly jump multiple levels by index or directory name with autocomplete and regex support. Inspect and dive into directories interactively with [`fzf`](https://junegunn.github.io/fzf/getting-started/)—and optionally track your path history for seamless recall.\n\nKiss tedious `cd ..` chains goodbye!\n\n## Bash Demo\n\n![vhs animation showing the up script in action](assets/up_vhs_demo_animation.gif \"See `up` in action using charmbracelet's `vhs` tool in Bash!\")\n\n*Animated GIF generated programmatically with [`vhs`](https://github.com/charmbracelet/vhs)*\n\n## Zsh Demo\n\n![Manually recorded animation of the up script in action](assets/up_example_use_animation.gif \"See `up` in action with a handcrafted screengrab using Zsh!\")\n\n*Animated GIF captured manually with [LICEcap](https://www.cockos.com/licecap/)*\n\n## 📜 Table of Contents\n- [Key Features](#-key-features)\n- [Installation](#-installation)\n    - [Bash](#bash)\n    - [Zsh](#zsh)\n    - [Man Page (Optional)](#man-page-optional)\n- [Configuration](#-configuration)\n- [Usage](#-usage)\n    - [Jump by Index](#jump-by-index)\n    - [Jump to a Directory Name](#jump-to-a-directory-name)\n    - [Jump to a Directory Name Using Regex](#jump-to-directory-name-using-regex)\n    - [Jump by `fzf`](#jump-by-fzf-fuzzy-finderhttpsgithubcomjunegunnfzf)\n    - [Verbose Mode](#verbose-mode)\n    - [Navigation to `HOME` and Previous Paths](#navigate-to-home-and-previous-paths)\n    - [Output Style Environment Variables](#output-style-environment-variables)\n    - [Path History Navigation (Optional)](#path-history-navigation-optional)\n\n## ⭐ Key Features\n\n1. **Multi-Level Navigation**\n    - Jump up multiple directory levels by index:\n        - `up` (jumps one level)\n        - `up 2` (jumps two levels)\n        - `up 3` (jumps three levels)\n\n2. **Tab Completion**\n    - Autocomplete parent and ancestor directory names with auto-escape (e.g., `\\!\\[special\\ dir\\]/`).\n    - Supports Unicode directories (e.g., `ダン·メイソン/`, `日本語/`, `привет/`, emojis like `📂/`).\n\n3. **Regex-Based Navigation**\n    - Use `-r` for general matches, `-s` for \"starts with,\" `-e` for \"ends with,\" or `-x` for exact matches.\n    - Combine with `-i` for case-insensitivity or export `_UP_REGEX_DEFAULT=true` for default regex behavior.\n\n4. **Verbose Feedback**\n    - View directory change details with `-v` or enable persistent verbosity with `_UP_ALWAYS_VERBOSE=true`.\n    - Customize output colors with style variables or disable them with `_UP_NO_STYLES=true`.\n\n5. **History Features (Optional)**\n    - Track recently visited directories by exporting `_UP_ENABLE_HIST=true`.\n    - Jump history using `-F` (`fzf`) or the [](#ph-path-history-wrapper-function) wrapper.\n        - Use `up_passthru` to capture directory changes from `cd`, [`zoxide`](https://github.com/ajeetdsouza/zoxide), [`jump`](https://github.com/gsamokovarov/jump), etc.\n    - List history in order of recency with `-l`.\n    - Clear history using `-c`.\n\n6. **Error Handling**\n    - Provides proper exit codes and styled error messages (`_UP_ERR_STYLE`) for clarity; useful for scripts or shell prompts like [starship](https://starship.rs/).\n\n7. **Compatibility**\n    - Supports both Bash and Zsh, with minimal, standard tool dependencies ensuring fast performance.\n    - Optional integration with the fuzzy finder [`fzf`](https://github.com/junegunn/fzf), featuring [`tree`](https://oldmanprogrammer.net/source.php?dir=projects/tree), `ls`, and `stat` previews. (Or [`eza`](https://github.com/eza-community/eza) for `tree` and `ls` output, if available.)\n\n---\n\n## ⚙ Installation\n\n### Bash\n\nDownload the git repo to your preferred destination. For example:\n\n```sh\ngit clone https://github.com/LittleWalter/up ~/.local/share/shell/up\n```\n\nAdd to `.bashrc` or `.bash_profile` on Apple macOS systems:\n\n```bash\nsource ~/.local/share/shell/up/up.bash # The `up` function\nsource ~/.local/share/shell/up/up_completion.bash # `up` completion\n```\n\n#### Quick Bash Installation\n\nAssuming your Bash config is at `~/.bashrc`, use this snippet to download and append the lines in one step:\n\n```sh\ngit clone https://github.com/LittleWalter/up ~/.local/share/shell/up\necho 'source ~/.local/share/shell/up/up.bash' \u003e\u003e ~/.bashrc\necho 'source ~/.local/share/shell/up/up_completion.bash' \u003e\u003e ~/.bashrc\n```\n\n### Zsh\n\nDownload the git repo to your preferred destination. For example:\n\n```sh\ngit clone https://github.com/LittleWalter/up ~/.local/share/shell/up\n```\n\nThese scripts are fully compatible with Zsh using `bashcompinit`.\n\nThe `autoload` lines enable autocompletion modules.\n\nAdd to `.zshrc`:\n\n```bash\nautoload -U +X compinit \u0026\u0026 compinit # Enable Zsh completion \nautoload -U +X bashcompinit \u0026\u0026 bashcompinit # Enable Bash completion compatibility\n\nsource ~/.local/share/shell/up/up.bash # The `up` function\nsource ~/.local/share/shell/up/up_completion.bash # `up` completion\n```\n\n#### Quick Zsh Installation\n\nAssuming your Zsh config is at `~/.zshrc`, use this snippet to download and append the lines in one step:\n\n```sh\ngit clone https://github.com/LittleWalter/up ~/.local/share/shell/up\necho 'autoload -U +X compinit \u0026\u0026 compinit' \u003e\u003e ~/.zshrc\necho 'autoload -U +X bashcompinit \u0026\u0026 bashcompinit' \u003e\u003e ~/.zshrc\necho 'source ~/.local/share/shell/up/up.bash' \u003e\u003e ~/.zshrc\necho 'source ~/.local/share/shell/up/up_completion.bash' \u003e\u003e ~/.zshrc\n```\n\n### Man Page (Optional)\n\nThe man page for `up` provides detailed usage information that complements the `-h`/`--help` flags and this README. Installing it is optional but recommended for improved command-line documentation.\n\nTo install the man page, run the following commands:\n\n```sh\ncd ~/.config/shell/up/man         # Navigate to the directory where the scripts are located\nchmod +x install_up_man_page.bash # Ensure the script is executable\n./install_up_man_page.bash        # Run the installation script\n```\n\nAfter installation, verify that the man page is available by running:\n\n```sh\nman up\n```\n\n### 📝 Sidenote on `HOME` Directory Organization\n\nFollowing best practices, I recommend using the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) to reduce `HOME` directory clutter.\n\nBy default, `XDG_CONFIG_HOME` is `$HOME/.config` and `XDG_DATA_HOME` is `$HOME/.local/share`. However, these paths might not be explicitly defined in your shell configuration; verify with `echo $XDG_CONFIG_HOME`.\n\nFor this project, somewhere within `XDG_DATA_HOME` makes sense.\n\nWithin your `.bashrc` or `.zshrc`, or more appropriately `.zshenv`, you may define these as environment variables:\n\n```sh\nexport XDG_CONFIG_HOME=\"$HOME/.config\" # Configuration files\nexport XDG_DATA_HOME=\"$HOME/.local/share\" # Persistent data storage\nexport XDG_CACHE_HOME=\"$HOME/.cache\" # Non-essential files such as shell command history, log files, etc.\n```\n\n---\n\n## ⚙ Configuration\n\n`up` offers two straightforward methods to configure environment variables: directly in your shell configuration or through an optional configuration file.\n\nFor a complete list of available environment variables and their default values, refer to `up --help` or consult the optional man page.\n\n### **Option 1:** Add to Your Shell Configuration\n\nDefine environment variables directly in your shell configuration file (`.bashrc`, `.zshrc`, or `.zshenv`). This approach integrates seamlessly into your existing shell setup:\n\n```bash\nexport _UP_ERR_STYLE=true\nexport _UP_HISTFILE=$HOME/.cache/up/up_history.log\nexport _UP_HISTSIZE=1000\nexport _UP_ALWAYS_VERBOSE=true\n...\n```\n\n### **Option 2:** Specify a Configuration File\n\nYou can centralize your environment variable definitions in a dedicated configuration file. By default, `up` looks for `~/.config/up/up_settings.conf`. To use a custom path, set the `_UP_CONFIG_FILE` environment variable:\n\n```bash\nexport _UP_CONFIG_FILE=$HOME/.config/up/my_custom_config.conf\n```\n\n#### Configuration File Format\n\nThe configuration file uses simple key-value pairs to define environment variables:\n\n```sh\n# ╻ ╻┏━┓   ┏━┓┏━╸╺┳╸╺┳╸╻┏┓╻┏━╸┏━┓ ┏━╸┏━┓┏┓╻┏━╸\n# ┃ ┃┣━┛   ┗━┓┣╸  ┃  ┃ ┃┃┗┫┃╺┓┗━┓ ┃  ┃ ┃┃┗┫┣╸\n# ┗━┛╹  ╺━╸┗━┛┗━╸ ╹  ╹ ╹╹ ╹┗━┛┗━┛╹┗━╸┗━┛╹ ╹╹\n# REF: `man up` or `up --help` for info on environent variables\n\n# Genenal Settings\n_UP_ALWAYS_VERBOSE=false\n\n# PWD Settings\n_UP_ALWAYS_IGNORE_CASE=false\n_UP_REGEX_DEFAULT=false\n_UP_FZF_PWDOPTS=(\n  --height=50%\n  --layout=reverse\n  --prompt=\" Path: \"\n  --header=\"󰌑 cd   ^P\"\n  --preview=\"eza --color=always --icons --tree {}\"\n  --bind=\"ctrl-p:toggle-preview\"\n  --bind=\"ctrl-l:change-preview(eza --color=always --icons -laah {})\"\n  --bind=\"ctrl-i:change-preview(echo '\\`stat\\`:'; ustat {})\"\n  --bind=\"ctrl-t:change-preview(eza --color=always --icons --tree {})\"\n  --bind=\"ctrl-j:preview-page-down,ctrl-k:preview-page-up\"\n  --preview-window=70%,border-double,top\n  --preview-label=\"[ 󰈍 ^L   ^T   ^I   ^J   ^K ]\"\n  # Catppuccin Mocha theme\n  --color=\"fg:#c6aad9,hl:#f5a97f\"\n  --color=\"fg+:#f4dbd6,bg+:#272935,hl+:#94e2d5\"\n  --color=\"info:#a6da95,prompt:#c6a0f6,pointer:#e28b83,marker:#94e2d5,spinner:#f5a97f,header:#e5c890\"\n)\n\n# History Settings\n_UP_ENABLE_HIST=true\n_UP_HISTFILE=$XDG_CACHE_HOME/up_history.log\n_UP_HISTSIZE=1000\n_UP_FZF_HISTOPTS=(\n  --height=50%\n  --layout=reverse\n  --prompt=\"󰜊 Path: \"\n  --header=\"󰌑 cd   ^P  󰮉^D   Missing Paths Omitted\"\n  --preview=\"eza --color=always --icons --tree {}\"\n  --bind=\"ctrl-p:toggle-preview\"\n  --bind=\"ctrl-l:change-preview(eza --color=always --icons -laah {})\"\n  --bind=\"ctrl-i:change-preview(echo '\\`stat\\`:'; ustat {})\"\n  --bind=\"ctrl-t:change-preview(eza --color=always --icons --tree {})\"\n  --bind=\"ctrl-d:execute(rmd -l {})\" # Run custom `rm -rf` script\n  --preview-window=hidden\n  --bind=\"ctrl-j:preview-page-down,ctrl-k:preview-page-up\"\n  --preview-window=70%,border-double,top\n  --preview-label=\"[ 󰈍 ^L   ^T   ^I   ^J   ^K ]\"\n  # Catppuccin Mocha theme\n  --color=\"fg:#b7bdf8,hl:#f4dbd6\"\n  --color=\"fg+:#f4dbd6,bg+:#272935,hl+:#c6a0f6\"\n  --color=\"info:#94e2d5,prompt:#f5c2e7,pointer:#f5a97f,marker:#94e2d5,spinner:#e28b83,header:#a6da95\"\n)\n_UP_EXCLUDED_PATHS=(\n  \"$HOME\"\n)\n\n# Style Settings: Catppuccin Mocha theme\n_UP_NO_STYLES=false\n_UP_DIR_CHANGE_STYLE=\"\\033[38;2;249;226;175m\"\n_UP_ERR_STYLE=\"\\033[48;2;243;160;168m\\033[38;2;30;30;46m\"\n_UP_PWD_STYLE=\"\\033[38;2;166;227;161m\"\n_UP_OLDPWD_STYLE=\"\\033[38;2;88;91;112m\"\n_UP_REGEX_STYLE=\"\\033[38;2;116;199;236m\"\n```\n\nEnvironment variables are expanded automatically (e.g., `$HOME` becomes `/home/user`). Variables defined in the shell configuration take precedence over those in the configuration file, allowing flexibility.\n\n---\n\n## ⌨ Usage\n\n![up --help screenshot](assets/up_help_screenshot.jpg \"`up --help` has detailed usage information\")\n\n### Jump by Index\n\n```sh\n$ up \u003coptional: integer\u003e\n```\n\n#### Jump 1 Directory\n\n```sh\n$ pwd\n/Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\n$ up\n$ pwd\n/Volumes/WD_SSD_1TB/Pictures/wallpapers\n```\n\n#### Jump 3 Directories\n\n```sh\n$ up 3\n$ pwd\n/Volumes/WD_SSD_1TB\n```\n\n### Jump to a Directory Name\n\n#### Display the Autocomplete List\n\n```sh\n$ up \u003ctab\u003e\n/            Pictures/    Volumes/     WD_SSD_1TB/  wallpapers/\n```\n\n#### Autocomplete Directory Name with Prefix\n\nTo autocomplete the only directory that starts with `Pic`:\n\n```sh\n$ up Pic\u003ctab\u003e\n$ up Pictures/\n```\n### Jump to Directory Name Using Regex\n\n- **`-i` / `--ignore-case`**: Perform case-insensitive regex jumps with the `-s`, `-e`, and `-r` flags.\n- **`-s` / `--starts-with`**: Jump to the nearest directory that starts with a given regex pattern.\n    - Automatically prefixes your regex with `^` for matching at the start.\n- **`-e` / `--ends-with`**: Jump to the nearest directory that ends with a given regex pattern.\n    - Appends your regex with `$` for matching at the end.\n- **`-r` / `--regex`**: Jump to the nearest directory that matches any part of your regex.\n- **`-x` / `--exact`**: Jump to an exact directory name match (default behavior).\n    - Useful when `_UP_REGEX_DEFAULT=true` is exported for regex-based navigation by default.\n\nExample: To jump to the closest directory containing `SSD` within `/Volumes/WD_SSD_1TB/Pictures/wallpapers/apple`:\n\n```sh\n$ up -r SSD\n$ pwd\n/Volumes/WD_SSD_1TB\n```\nExample: To jump to the same location ignoring case:\n\n```sh\n$ up -i ssd\n$ pwd\n/Volumes/WD_SSD_1TB\n```\n\n\n#### `_UP_REGEX_DEFAULT` Environment Variable\n\nPrefer regex-based navigation every time without the need for explicit flags? Add the following line to `.bashrc`, `.zshrc`, or `.zshenv`:\n\n\n```sh\nexport _UP_REGEX_DEFAULT=true\n```\n\nUse the `-x` flag for exact matches to temporarily disable this behavior.\n\n```sh\n$ pwd\n/Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\n$ up -x Volumes\n$ pwd\n/Volumes\n```\n\n##### Alias Tip\n\nSimplify your workflow by setting up aliases while preserving default behavior. Add to `.bashrc` or `.zshrc`:\n\n```sh\nalias u='up -i'         # Jump to the nearest regex match, ignore case\nalias m='up -m'         # Open most frequently visited paths in `fzf`\nalias recent='up -R 1d' # List paths accessed in the last day\n```\n\nCheck for conflicts using `command -v \u003calias\u003e`.\n\n### Jump by [`fzf` (Fuzzy Finder)](https://github.com/junegunn/fzf)\n\nUse an optional interactive fuzzy finder to jump directories in your PWD, use the `-f` / `--fzf` flags.\n\n```sh\n$ up -f\n$ up --fzf\n```\n\n#### Customizing `fzf` Options for Ancestor Paths (`PWD`)\n\nWhen [`eza`](https://github.com/eza-community/eza) is not installed, the default `fzf` options for listing ancestor paths of the current working directory are:\n\n```sh\nFZF_PWDOPTS_DEFAULT=(\n\t--height=50%\n\t--layout=reverse\n\t--prompt=\" Path: \"\n\t--header=\"󰌑 cd   ^P\"\n\t--preview=\"tree -C {}\"\n\t--bind=\"ctrl-l:change-preview(ls --color=always -lAh {})\"\n\t--bind=\"ctrl-i:change-preview(echo '\\`stat\\` Information:'; stat {})\"\n\t--bind=\"ctrl-t:change-preview(tree -C {})\"\n\t--bind=\"ctrl-p:toggle-preview\"\n\t--bind=\"ctrl-j:preview-page-down,ctrl-k:preview-page-up\"\n\t--preview-window=70%,border-double,top\n\t--preview-label=\"[ 󰈍 ^L   ^T   ^I   ^J   ^K ]\"\n)\n```\n**NOTE**: The [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts) for [icons](https://www.nerdfonts.com/) might not render in this Markdown file.\n\nIf `eza` is installed, then the `tree` and `ls` respective equivalents are used for preview for icon support: `eza --color=always --tree --icons {}`, `eza --color=always --icons -laah {}`.\n\nDefault `fzf` keybinds:\n\n* `Ctrl-P`: Toggle preview\n* `Ctrl-J` / `Ctrl-K`: Preview PGUP/PGDN\n* `Ctrl-T`: [`tree`](https://github.com/Old-Man-Programmer/tree) in preview\n* `Ctrl-L`: `ls --color=always -lAh` in preview\n* `Ctrl-I`: `stat` information in preview\n\nThe line `--layout=reverse` will display `fzf` below the prompt line; `--height=50%` uses half of the available terminal emulator window.\n\n##### Example: `fzf` Options for Ancestor Paths (`PWD`)\n\nTo customize the display of `fzf`, export `_UP_FZF_PWDOPTS` within `.bashrc`, `.zshrc`, or `.zshenv`.\n\nFor example,\n\n```sh\n# Define an array of fzf options for PWD\n_UP_FZF_PWDOPTS=(\n\t--height=50%\n\t--layout=reverse\n\t--prompt=\"Select: \"\n\t--preview=\"ls -A {}\"\n\t--bind=\"ctrl-p:toggle-preview\"\n)\nexport _UP_FZF_PWDOPTS\n```\n\nFor inspiration, check out this [detailed `fzf` guide](https://thevaluable.dev/practical-guide-fzf-example/).\n\n### Verbose Mode\n\nJust like the `cd` command, `up` will generally not output text upon successful execution.\n\nTo display extra information such as `$OLDPWD` and `$PWD` after calling `up`:\n\n```sh\n$ up -v [integer or directory name]\n$ up --verbose [integer or directory name]\n```\n\n#### Verbose Mode Examples\n\n```sh\n$ up -v Pictures/\nup: jumped 2 dirs to nearest: Pictures\nold: /Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\npwd: /Volumes/WD_SSD_1TB/Pictures\n```\n\n```sh\n$ up verbose 2\nup: jumped 2 dirs\nold: /Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\npwd: /Volumes/WD_SSD_1TB/Pictures\n```\n\n#### `_UP_ALWAYS_VERBOSE` Environment Variable\n\nPrefer verbose mode every time without polluting your aliases? Add the following line to `.bashrc`, `.zshrc`, or `.zshenv`:\n\n```bash\nexport _UP_ALWAYS_VERBOSE=true\n```\n\n### Navigate to `HOME` and Previous Paths\n\nFor the sake of completeness, navigating to your `HOME` and previous paths are included.\n\n`HOME` is the only valid full path `up` allows; all other arguments must be a single directory name.\n\nYou don't have to be in a `HOME` directory for this to work.\n\n```sh\n$ pwd\n/Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\n$ up ~\n$ pwd\n/home/mwallace\n$ up -\n$ pwd\n/Volumes/WD_SSD_1TB/Pictures/wallpapers/apple\n```\n\n### Output Style Environment Variables\n\nDefine output styles to tailor how directory changes, errors, and other terminal messages appear. Setting environment variables allows you to enhance readability and match colors to your terminal theme.\n\nSet ANSI escape sequences in your shell configuration file (i.e., `.bashrc`, `.zshrc`, or `.zshenv`) to avoid editing `up.bash` manually.\n\n* `_UP_DIR_CHANGE_STYLE` for the number of parent directories jumped.\n    - Default: Orange (`\\033[0;33m`)\n* `_UP_ERR_STYLE` for error messages.\n    - Default: Red (`\\033[0;31m`)\n* `_UP_OLDPWD_STYLE` for the previous directory.\n    - Default: Light Gray (`\\033[0;37m`)\n* `_UP_PWD_STYLE` for your current working directory.\n    - Default: Light Green (`\\033[0;32m`)\n* `_UP_REGEX_STYLE` for regular expression patterns, e.g., `'^big_kahuna_.urger$'`.\n    - Default: Cyan (`\\033[0;36m`)\n\nDefault values represent standard ANSI colors, which work reliably across most terminal emulators.\n\nSome terminal emulators may be flexible displaying basic colors and automatically match your preconfigured terminal theme, depending on the capabilities of your terminal emulator (e.g., [WezTerm](https://wezterm.org/) for advanced color support).\n\nRefer to [this GitHub Gist](https://gist.github.com/JBlond/2fea43a3049b38287e5e9cefc87b2124) for more styling ideas.\n\n#### Example: Custom Style Theming\n\nIf your terminal emulator supports the full RGB spectrum, you may define style variables using a mix-and-match of foreground (`\\033[38;2;\u003cr\u003e;\u003cg\u003e;\u003cb\u003em`) and background (`\\033[48;2;\u003cr\u003e;\u003cg\u003e;\u003cb\u003em`) colors.\n\n```bash\n# `up` style theme: based on Catppuccin Mocha\n# REF: https://github.com/catppuccin/catppuccin\n# NOTE: ANSI escape format\n#       Foreground = \"\\033[38;2;\u003cr\u003e;\u003cg\u003e;\u003cb\u003em\"\n#       Background = \"\\033[48;2;\u003cr\u003e;\u003cg\u003e;\u003cb\u003em\"\nexport _UP_DIR_CHANGE_STYLE=\"\\033[38;2;249;226;175m\" # Yellow\nexport _UP_ERR_STYLE=\"\\033[48;2;243;160;168m\\033[38;2;30;30;46m\" # Red background, \"Crust\" foreground\nexport _UP_OLDPWD_STYLE=\"\\033[38;2;88;91;112m\" # \"Surface2\"\nexport _UP_PWD_STYLE=\"\\033[38;2;166;227;161m\" # Green\nexport _UP_REGEX_STYLE=\"\\033[38;2;116;199;236m\" # Sapphire\n```\n![up example using the Catppuccin Mocha theme for style output](assets/up_catppuccin_mocha_theme_example.jpg \"Style example: Catppuccin Mocha theme in WezTerm\")\n\n#### Turning Off Styling\n\nTo turn off styling and display plaintext only, add the following line to `.bashrc`, `.zshrc`, or `.zshenv`:\n\n```bash\nexport _UP_NO_STYLES=true\n```\n\n### Path History Navigation (Optional)\n\nTo track path history with `up`, add to `.bashrc`, `.zshrc`, or `.zshenv`:\n\n```bash\nexport _UP_ENABLE_HIST=true\n```\n\nBy default, the path history file is located at `~/.cache/up_history.log` with a maximum size (in lines) of 250.\n\nExport the `_UP_HISTFILE` and `_UP_HISTSIZE` to your preferred path and maximum size in `.bashrc`, `.zshrc`, or `.zshenv`.\n\n```bash\nexport _UP_HISTFILE=\"$XDG_CACHE_HOME/up/up_path_history.log\"\nexport _UP_HISTSIZE=1000\n```\n\nExclude paths from history logging with the `_UP_EXCLUDED_PATHS` environent variable in `.bashrc`, `.zshrc`, or `.zshenv`:\n\n```bash\n_UP_EXCLUDED_PATHS=(\n  \"$HOME\"\n  \"$HOME/.Trash\"\n  \"$HOME/.ssh\"\n  \"/tmp\"\n  \"/var/log\"\n)\nexport _UP_EXCLUDED_PATHS\n```\n\n#### List All History Entries\n\nWhile the history file is ordered by oldest to newest, path histories are indexed by most recent.\n\n```sh\n$ up -l\n$ up --list-hist\n```\n\nTo show the list of most frequently visited paths, use `-L`, `--list-freq` flags:\n\n```sh\n$ up -L\n$ up --list-freq\n```\n\n#### Jump to a Specific History Index\n\nTo jump to an index, use the `-j` / `--jump-hist` flags:\n\n```sh\n$ up -j 34 # jump to the 34th most recent tracked path\n```\n\n#### Show the Current History Size\n\nDisplay the size of the history with `-S` / `--size`:\n\n```sh\n$ up --size\nup: history size: [=================...] 88% (221/250)\n```\n\n#### Clear and Prune History Entries\n\nClear history entries with `-c` / `--clear` and passing a timeframe argument in the form `\u003cinteger\u003e(min|h|d|m)`, where `min` represents minutes, `h` for hours, `d` for days, and `m` for months.\n\nFor example, to remove history entries older than 5 days:\n\n```sh\n$ up --clear 5d\nup: cleared 31 history entries older than 5d: /home/mrpink/.cache/up_history.log\n```\n\nTo clear all history, pass no timeframe argument:\n\n```sh\n$ up -c\nup: history file cleared: /home/mrpink/.cache/up_history.log\n```\n\nUse the verbose flag (`-v`) before `-c` / `--clear` to display and confirm the removed paths.\n\n```sh\n$ up -vc 12h\nRemoving 14 Entries:\n  2025-04-13 22:58:09 /home/dietpi\n  2025-04-13 23:34:30 /home/dietpi/.cache\n  2025-04-13 23:36:25 /home/dietpi\n  2025-04-14 01:51:14 /home/dietpi/.local\n  2025-04-14 01:51:19 /home/dietpi/.local/share\n  2025-04-14 01:51:24 /home/dietpi/.local/share/bin\n  2025-04-14 01:51:36 /home/dietpi\n  2025-04-14 01:52:39 /home/dietpi/bin\n  2025-04-14 01:54:11 /home/dietpi\n  2025-04-14 01:59:55 /home/dietpi/.local/share/bin\n  2025-04-14 02:00:06 /home/dietpi/.local/share/bin/.fzf\n  2025-04-14 02:00:14 /home/dietpi/.local/share/bin/.fzf/bin\n  2025-04-14 02:00:38 /home/dietpi\n  2025-04-14 02:07:08 /home/dietpi/.config\n  2025-04-14 02:07:15 /home/dietpi\nConfirm clear of path history entries older than 12h (Y/n): y\nup: cleared 14 history entries older than 12h: /home/dietpi/.cache/up_history.log\n```\n\nPrune missing paths in history file with `-p` / `--prune-hist`:\n\n```sh\n$ up --prune-hist\nup: pruned history: removed 28 invalid paths (24 remaining, max: 250)\n```\n\n#### Use `fzf` (Fuzzy Finder) to Inspect and Jump Path History\n\n```sh\n$ up -F\n$ up --fzf-hist\n```\n\nTo filter by most recent paths, use `-R`, `--fzf-recent` flags passing `\u003cinteger\u003e[min|h|d|m]` argument:\n\n```sh\n$ up -R                 # Paths accessed in the last hour\n$ up --fzf-recent 15min # Paths accessed in the last 15 minutes\n$ up -R 5h              # Paths accessed in the last 5 hours\n$ up -R 2d              # Paths accessed in the last 2 days\n$ up -R 1m              # Paths accessed in the last month\n```\n\nTo filter by the most frequently visited paths, use `-m`, `--fzf-freq` flags:\n\n```sh\n$ up -m\n$ up --fzf-freq\n```\n\n##### Customizing `fzf` Options for Paths in History\n\nWhen [`eza`](https://github.com/eza-community/eza) is not installed, the default `fzf` options for listing historic paths are:\n\n```sh\nFZF_HISTOPTS_DEFAULT=(\n\t--height=50%\n\t--layout=reverse\n\t--prompt=\"󰜊 Path: \"\n\t--header=\"󰌑 cd   ^P   Missing Paths Omitted\"\n\t--preview-window=hidden\n\t--preview=\"tree -C {}\"\n\t--bind=\"ctrl-l:change-preview(ls --color=always -lAh {})\"\n\t--bind=\"ctrl-t:change-preview(tree -C {})\"\n\t--bind=\"ctrl-i:change-preview(echo '\\`stat\\` Information:'; stat {})\"\n\t--bind=\"ctrl-p:toggle-preview\"\n\t--bind=\"ctrl-j:preview-page-down,ctrl-k:preview-page-up\"\n\t--preview-window=70%,border-double,top\n\t--preview-label=\"[ 󰈍 ^L   ^T   ^I   ^J   ^K ]\"\n)\n```\n\nThe preview window is hidden by default; `Ctrl-P` to toggle the preview window.\n\nIn the header, \"Missing Paths Omitted\" denotes non-jumpable paths in history are skipped.\n\n##### Example: `fzf` Options for Paths in History\n\nTo customize the display of `fzf`, export `_UP_FZF_HISTOPTS` within `.bashrc`, `.zshrc`, or `.zshenv`.\n\n```sh\n# Example: Define array-based fzf options w/ `ls -A` preview\n_UP_FZF_HISTOPTS=(\n    --height=50%\n    --layout=reverse\n    --prompt=\"Select: \"\n    --preview=\"ls -A {}\"\n    --bind=\"ctrl-p:toggle-preview\"\n)\nexport _UP_FZF_HISTOPTS\n```\n\n#### `up` Wrapper Functions\n\nTo access the following wrapper functions, set the `_UP_ENABLE_HIST` environment variable within `.bashrc`, `.zshrc`, or `.zshenv`:\n\n```bash\nexport _UP_ENABLE_HIST=true\n```\n\n##### `up_passthru` Helper Function\n\nBy default, `up` only tracks its own path history when `_UP_ENABLE_HIST=true` is exported.\n\nTo capture and track global path histories, use the `up_passthru` helper function by adding aliases to `.bashrc` and `.zshrc`.\n\n```bash\n# up: Global history logging \nalias cd='up_passthru cd' # cd: Use `builtin cd -- \u003cpath\u003e` to a skip logging\nalias z='up_passthru z'   # zoxide\n```\n\n##### `ph` (Path History) Wrapper Function\n\n`ph` is a wrapper for `up` that focuses on path history navigation.\n\nIf you are tracking path history of `cd`, `zoxide`, `jump`, etc., using `up_passthru`, this is a more intuitive interface.\n\n![ph --help screenshot](assets/ph_help_screenshot.jpg \"`ph --help` is an `up` wrapper for path history\")\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlewalter%2Fup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flittlewalter%2Fup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlewalter%2Fup/lists"}