Package: cdhist
Linux Directory Historycdhistis a utility which
provides a Linux shellcd historydirectory stack. A shellcdwrapper function calls cdhist to intercept your typedcdcommand and
maintain an ordered stack of all directories you have previously visited
which can be listed and quickly navigated to.cdhistcan also be used with theCommand Line Fuzzy Finderfzfto
fuzzy search and select on previously visited directories, and can be
used to easilycdbetweengit worktreedirectories. See the sections below aboutFZF
IntegrationandGit Worktree
Integration.The latest version and documentation is available athttp://github.com/bulletmark/cdhist.Example UsageUse thecdcommand to change directory as normal:$cd/tmp
$cd/etc
$cd/usr/share/doc
$cd/boot/loader
$cd~/etc
$cdAt any point you can use thecd --command to list all your previously
visited directories and be prompted for one to select andcdto:$ cd --
  6 ...
  5 /tmp
  4 /etc
  3 /usr/share/doc
  2 /boot/loader
  1 ~/etc
  0 ~
Select index [or <enter> to quit]: 3
$ pwd
/usr/share/docThat's it! The above is all you really need to know. Instead of having
to type the directory name you merely enter it's index. The directories
are displayed most recently visited last, without duplicates. Index 0 is
the current directory, index 1 is the previous, index 2 is the second
previous, up to a user configurable number (default 50). Other available
commands and options are:List the current stack and its indices (without prompting):$cd-lChange immediately to directory corresponding to stack index 4:$cd-4Search back through stack for directory containing "string" andcdthere:$cd-/stringNote, you can also typestringat thecd --prompt to search.Show help/usage:$cd-hInstallationArch users can installcdhist from the
AURand skip to the next
section.Python 3.7 or later is required. Notecdhist is on
PyPIso just ensure thatpipxis installed then type the
following:$ pipx install cdhistTo upgrade:$ pipx upgrade cdhistSetupA user who wants to use the cdhist facility should add the following
lines to their~/.bashrcor~/.zshrcfile (after where your PATH is
set up so that the commandcdhistcan be found). This creates thecdwrapper command in your interactive shell session as a tiny function.
Note you cancustomize the command nameif
you want.iftypecdhist&>/dev/null;then.<(cdhist-i)fiThen log out and back in again.FZF IntegrationThe popularCommand Line Fuzzy Finderfzfcan easily be integrated with cdhist to provide fuzzy search
navigation over your directory history. Set the following in your
environment to havefzfsearch the directories recorded by cdhist:exportFZF_ALT_C_COMMAND="cat$HOME/.cd_history"Sincefzfversion 0.31.0, you also should make a small change to the
way you source thefzfcompletion and key-binding files into your
shell, e.g. in your~/.bashrc. The following is a typical script to
loadfzfexcept the source line must be changed to do an "on the
fly" edit ofbuiltin cdto regularcd. E.g:for_din/usr/share/fzf/usr/share/fzf/shell/usr/share/doc/fzf/examples\/usr/share/bash-completion/completions/fzf;doif[[-d$_d]];thenfor_fin$_d/key-bindings.bash$_d/completion.bash;doif[[-f$_f]];then.<(sed's/builtin cd/cd/'$_f)fidonefidoneAfter doing this (and reloading your shell session), you can use thefzfkey binding<ALT+C>to havefzflist all your previous
directories and fuzzy match on them for selection as you type.fzfcan
also provide fancydirectory
previewsusingtree, etc. Of course the cdhist native commandcd --and
other cdhist commands described above are still available, in addition
to thefzfkey binding.Pruning Non-Existent DirectoriesIf you prefer that directories that do not exist are excluded fromfzfand yourcdhistory (i.e. exclude directories that have been deleted
since they were last visited), then you can define thefzfcommand as:exportFZF_ALT_C_COMMAND="cdhist -p && cat$HOME/.cd_history"An alternative is to always exclude non-existent directories from your
cd history by setting the--prune-alwaysas adefault
option.Alternative Command NameSome people may prefer not to alias their systemcdcommand to this
utility and just use an alternative unique command name. To do this,
simply add your desired command name as an extra argument to thecdhistcommand in your shell initialization code. E.g, to use the
command namexdrather thancd, use the following in
your~/.bashrcor~/.zshrcfile:iftypecdhist&>/dev/null;then.<(cdhist-ixd)fiThen log out/in, and then just typexd /tmpto change dir,xd --to see
and select directories, etc.GIT Worktree Integrationcdhistcan be used to easilycdbetweengit worktreedirectories. You use thecd -gcommand to list all your worktrees and
be prompted for one to select, and then you will be switched to the
associated directory, and it will be added to yourcdhistory.# Current directory:$pwd/home/mark/src/myprog# List worktrees using standard git command:$gitworktreelist
/home/mark/src/myprogf76b8e0[main]/home/mark/src/development9796714[development]/home/mark/src/milestone1bc921b8[milestone1]/home/mark/src/teste6d965a[test]# Alternately, use cdhist to list worktrees and choose one to navigate to:$cd-g3~/src/development9796714[development]2~/src/milestone1bc921b8[milestone1]1~/src/teste6d965a[test]0~/src/myprogf76b8e0[main]Selectindex[or<enter>toquit]:2$pwd/home/mark/src/milestone1# Or, use cdhist to navigate to worktree dir for given branch name or# commit:$cd-gmain
$pwd/home/mark/src/myprogInstead of having to type the full git repository directory name you
merely are prompted with a list and enter it's index. Or just directly
enter the branch name (or commit hash). The directories are displayed in
the same order as the output of thegit worktree listcommand, except
that the git directory corresponding to the current working directory is
shown first (index 0) consistent with how the current directory is shown
at index 0 for normal cd history and thus conveniently showing you which
git worktree you are currently in whichgit worktree listunfortunately does not show.In you enter text instead of an index, you only need to enter as much of
the branch name, or commit hash, as needed to be unique. Note thatcd -gnicely presents paths based from your HOME directory with a tilde
(~) unlike the longer full path displayed bygit worktree list(although you can change that with the-u/--no-useroption, likely set
as adefault option).Relative Git Worktree DirectoriesThegit worktree listcommand displays absolute directory paths, and
cdhist does also by default, but many users prefer them displayed
as relative paths. The Git worktree command does not provide this but
you can enable it in cdhist by adding the-r/--relativeoption, e.g:$cd-gr3../development9796714[development]2../milestone1bc921b8[milestone1]1../teste6d965a[test]0.f76b8e0[main]Selectindex[or<enter>toquit]:Most likely you will want to set this as your default so do that by
adding--relativeas adefault option.Git Worktree Functionality AloneSome users may want the git worktree functionality provided by cdhist
but are not interested in the standardcdhistory functionality, or
alternately, want to use a completely separate command for the git
worktree functionality. To do this, simply add your desired command name
and the git option as an extra argument to thecdhistcommand in your
shell initialization code. E.g, to use the command namewtfor git
worktree functionality (only), add the following in your~/.bashrcor~/.zshrcfile:iftypecdhist&>/dev/null;then.<(cdhist-i"wt -g")fiThen log out/in, and then just typewtto list the git worktrees and
be prompted to select the directory etc. Of course, you can define thiswtcommand in parallel to using cdhist for yourcdcommand if
you want.Default OptionsThere are 2 alternatives to set default cdhist options:Set options in startup configuration file.Set options in shell initialization code.It's largely personal preference which you choose.Note if you set-r/--git-relativeor-u/--no-useroptions as default
then options-R/--no-git-relativeand-U/--userexist to
allow you to temporarily override those defaults.Set Options in Startup Configuration FileYou can add default options to a personal configuration file~/.config/cdhist-flags.conf. If that file exists then each line in
the file will be concatenated and automatically prepended to your command
line options. The following options are sensible candidates to set as
default options:--purge-always,--git-relative,--no-user,--size. Comments on any line are excluded.You are best to use the full/long name for options and to add them on
individual lines in the file so they are easy to read and easy to
comment out temporarily etc.Set Options in Shell Initialization CodeAlternately, just set your preferred default options in your shell
initialization code, e.g:iftypecdhist&>/dev/null;then.<(cdhist-i"cd -arm 200")fiThe above sets-a (--purge-always),-r (--git-relative), and-m (--size) 200options as defaults for yourcdcommand. Best to use
the short option names to keep the imported shell function definition
concise.An advantage of this 2nd approach to setting default options is that you
can create one alias for yourcdcommand, and another alias for your
git worktree command (e.g.wt), and both can have different cdhist
options.Command Line UsageTypecdhist -hto view the usage summary:usage: cdhist [-i] [-h] [-p] [-a] [-g] [-r] [-R] [-u] [-U] [-l] [-m SIZE]
                   [-n NUM_LINES] [-L] [-P] [-V]
                   [directory]

A Linux shell directory stack "cd history" function.

positional arguments:
  directory             directory (or branch for git worktree) to cd to, or
                        "--" to list history and prompt, or "-n" for n'th
                        entry in list or "-/<string>" to match for "string" in
                        dir

options:
  -i, --init            output shell initialization code. Optionally specify
                        alternative command name as argument, default="cd"
  -h, --help            show help/usage
  -p, --purge           just purge non-existent directories from history
  -a, --purge-always    always purge non-existent directories every write
  -g, --git             show git worktree directories instead
  -r, --git-relative    show relative git worktree paths instead of absolute
  -R, --no-git-relative
                        do not show relative git worktree paths (default)
  -u, --no-user         do not substitute "~" for home directory
  -U, --user            do substitute "~" for home directory (default)
  -l, --list            just list directory history
  -m SIZE, --size SIZE  maximum size of directory history (default=50)
  -n NUM_LINES, --num-lines NUM_LINES
                        limit output to specified number of lines
  -L, --follow-links    follow symbolic links (default=true)
  -P, --follow-physical
                        follow links to physical directory
  -V, --version         just output cdhist version

Note you can set default options in ~/.config/cdhist-flags.conf.LimitationsRegularcd, e.g. as provided by the bash builtin, offers some esoteric
command line options such as-eand-@, and shell options such asautocd,cdspell,cdable_vars. These rarely used options are not
supported by cdhist.Major Version Change HistoryVersion 3.0 changes and new features:Added function tocdbetweengit worktrees. Can configure this
as separate command if preferred, with option to display relative paths.Cleaner installation using-ioption so no need for separatecdhist.rcfile and can set arguments when installing to customise
command name + options etc.Added-L/-Pstandardcdoptions.Added-a/--purge-alwaysoption to always prune history.Add-n/--num-linesto limit number of lines in output (for-l/--listand--commands).Added ability to set default options in~/.config/cdhist-flags.conf.Parses options/arguments using standard Python argparse.Let setuptools build the main program stub rather than install our
own.Min Python version up from 3.4 to 3.7.Now installed as a Python package (directory) rather than a module
(single file).Some of these changes slow the program down but architecture is
changed so the program is run once only, not twice as it ran before.
Second run was to save the new directory aftercdhad validated it,
but now we validate it ourself before passing tocd. So net
performance is quicker than previous version, at least for the vanilla
case of changing directory. This is not noticeable on normal PC's but is
on constrained platforms like Raspberry Pi 2/3 using SD card.If you were previously settingCDHISTSIZEorCDHISTTILDEsettings
via environment variables then you now need to set them using--sizeand--no-userin~/.config/cdhist-flags.conf, or add those options
in your shell initialization code.The-soption to return acdhist.rcfile name for initialisation
is still currently supported for backwards-compatibility but is
undocumented and depreciated (a temporary file is created and returned).
It will likely eventually be removed.LicenseCopyright (C) 2010 Mark Blakeney. This program is distributed under the
terms of the GNU General Public License.
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or any later
version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License athttp://www.gnu.org/licenses/for more details.