| Name | cdhist JSON |
| Version |
4.1
JSON |
| download |
| home_page | None |
| Summary | Program to provide a Linux cd history directory stack |
| upload_time | 2025-01-31 22:48:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | GPLv3 |
| keywords |
bash
zsh
cd
fzf
git
worktree
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## CDHIST - Linux Directory History
[](https://pypi.org/project/cdhist/)
[](https://aur.archlinux.org/packages/cdhist/)
[cdhist](http://github.com/bulletmark/cdhist) is a utility which provides a
Linux shell **cd history** directory stack. A shell `cd` wrapper function calls
cdhist to intercept your typed `cd` command and maintain an ordered stack of
all directories you have previously visited which can be listed and quickly
navigated to.
[cdhist](http://github.com/bulletmark/cdhist) can also be used with a fuzzy
finder (such as [`fzf`][fzf]) to fuzzy search and select on previously visited
directories, and can be used to easily `cd` between [`git
worktree`](https://git-scm.com/docs/git-worktree) directories. See the sections
below about [Fuzzy Finder Integration](#fuzzy-finder-integration) and [Git
Worktree Integration](#git-worktree-integration).
The latest version and documentation is available at
http://github.com/bulletmark/cdhist.
## Example Usage
Use the `cd` command to change directory as normal:
```sh
$ cd /tmp
$ cd /etc
$ cd /usr/share/doc
$ cd /boot/loader
$ cd ~/etc
$ cd
```
At any point you can use the `cd --` command to list all your previously
visited directories and be prompted for one to select and `cd` to:
```
$ 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/doc
```
That'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 200).
If you prefer a more modern approach you can use a fuzzy finder such as
[`fzf`][fzf], or [`fzy`][fzy], or [`television`][television] to show and select
from the list, instead of a simple index prompt. See the section on [Fuzzy
Finder Integration](#fuzzy-finder-integration) below.
Other available commands and options are:
List the current stack and its indices (without prompting):
```sh
$ cd -l
```
Change immediately to directory corresponding to stack index 4:
```sh
$ cd -4
```
Search back through stack for directory containing "string" and `cd`
there:
```sh
$ cd -/string
```
Note, you can also type `string` at the `cd --` prompt to search.
Show help/usage:
```sh
$ cd -h
```
## Installation
Arch users can install [cdhist from the
AUR](https://aur.archlinux.org/packages/cdhist/) and skip to the next section.
Python 3.8 or later is required. Note [cdhist is on
PyPI](https://pypi.org/project/cdhist/) so the easiest way to install it is to
use [`uv tool`][uvtool] (or [`pipx`][pipx] or [`pipxu`][pipxu]).
```sh
$ uv tool install cdhist
```
To upgrade:
```sh
$ uv tool upgrade cdhist
```
To uninstall:
```sh
$ uv tool uninstall cdhist
```
## Setup
A user who wants to use the cdhist facility should add the following line to
their `~/.bashrc` or `~/.zshrc` file. Ensure it is added after where your PATH
is set up so that the command `cdhist` can be found. This creates the `cd`
wrapper command in your interactive shell session as a tiny function.
```sh
source <(cdhist -i)
```
Then log out and back in again to activate the new `cd` function. Note assuming
a normal `.bashrc` environment, this will alias your `cd` command in your
interactive terminal session only. The remapped `cd` will not be invoked by any
programs or scripts you run, or for other users etc.
### Alternative Command Name
Some people may prefer not to alias their real `cd` command to this utility and
just use an alternative unique command name. To do this, simply add your
desired command name as the first argument to the `cdhist -i` option in your
shell initialization code. E.g, to use the command name `xd` rather than `cd`,
use the following in your `~/.bashrc` or `~/.zshrc` file:
```sh
source <(cdhist -i xd)
```
Then log out/in, and then use `xd /tmp` to change dir, `xd --` to see and
select directories, etc.
### Default Options
You can set default cdhist options by appending options in the shell
initialization code, e.g:
```sh
source <(cdhist -i "cd -arm 100")
```
The above sets `-a (--purge-always)`, '' `-r (--git-relative)`, and `-m
(--size) 100` options as defaults for your `cd` command.
Note you can use multiple source lines to define multiple commands. E.g. define
one alias for your `cd` command, and another alias for your git worktree
command (e.g. `wt`). Both can have different cdhist options.
The following options are sensible candidates to set as default options:
`-m/--size`, `-a/--purge-always`, `-g/--git`, `-r/--git-relative`,
`-u/--no-user`, `-F/--fuzzy`, `-G/--no-fuzzy-git`.
Note if you set `-r/--git-relative` or `-u/--no-user` options as default then
options `-R/--no-git-relative` and `-U/--user` exist to allow you to
temporarily override those defaults via the command line.
### Fuzzy Finder Integration
Any of the popular command line fuzzy search finders such as [`fzf`][fzf], or
[`fzy`][fzy], or [`television`][television] can be used with `cdhist`.
E.g. to use [`fzf`][fzf]:
```sh
source <(cdhist -i "cd -F fzf")
```
Or, to use [`television`][television]:
```sh
source <(cdhist -i "cd -F \"tv --no-preview\"")
```
Now when you type `cd --` you will be prompted with a list of directories via
your fuzzy finder so you can search for a directory to select by fuzzy text
matching.
In the following description, [`fzf`][fzf] will be used as it is by far the
most popular fuzzy finder and the one used by the author. When you set up `fzf`
[shell integration](https://junegunn.github.io/fzf/shell-integration/) then you
can use the following terminal key bindings for `fzf`:
- `CTRL+t` to select files,
- `CTRL+r` to select commands,
- `ATL+c` to select directories.
However, I never use the last `ATL+c` function because it lists directories
only under the current directory whereas I am much more interested in listing
all directories I have previously visited, i.e. those maintained by cdhist. So
I disable that function in `fzf` by setting the `FZF_ALT_C_COMMAND` to an empty
string before I source `fzf` in my `.bashrc` when [setting `fzf` up](https://junegunn.github.io/fzf/shell-integration/#setting-up-shell-integration).
Then I set the following shell key binding in my `~/.inputrc` file (need to
restart your shell to activate):
```sh
"\ec": "cd --\n"
```
Now pressing `ALT+c` invokes cdhist to bring up the `fzf` list of my previously
visited directories. Alternately, use `ALT+d` for cdhist and keep `ALT+c` for
the default `fzf` search behavior.
You also have the choice of keeping the standard `cd --` command to work with
simple index selection, and map a different cdhist command name to use with
`ALT+c` only for the fuzzy finder. To do this, add the following 2 lines to your
`~/.bashrc` or `~/.zshrc` file:
```sh
source <(cdhist -i)
source <(cdhist -i "cdfuzzy -F fzf")
```
And then in your `~/.inputrc`:
```
"\ec": "cdfuzzy --\n"
```
Note all the above assumes you have the fuzzy finder somewhere in your PATH. If
you don't then just specify the full path, e.g:
```sh
source <(cdhist -i "cd -F /path-to/fzf")
```
### GIT Worktree Integration
[cdhist](http://github.com/bulletmark/cdhist) can be used to easily `cd`
between [git worktree](https://git-scm.com/docs/git-worktree)
directories. You use the `cd -g` command 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 your `cd` history.
```sh
# Current directory:
$ pwd
/home/mark/src/myprog
# List worktrees using standard git command:
$ git worktree list
/home/mark/src/myprog f76b8e0 [main]
/home/mark/src/development 9796714 [development]
/home/mark/src/milestone1 bc921b8 [milestone1]
/home/mark/src/test e6d965a [test]
# Alternately, use cdhist to list worktrees and choose one to navigate to:
$ cd -g
3 ~/src/development 9796714 [development]
2 ~/src/milestone1 bc921b8 [milestone1]
1 ~/src/test e6d965a [test]
0 ~/src/myprog f76b8e0 [main]
Select index [or <enter> to quit]: 2
$ pwd
/home/mark/src/milestone1
# Or, use cdhist to navigate to worktree dir for given branch name or
# commit:
$ cd -g main
$ pwd
/home/mark/src/myprog
```
Instead 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 the `git worktree list` command, 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 which `git worktree list` unfortunately 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 that `cd -g` nicely
presents paths based from your HOME directory with a tilde (`~`) unlike the
longer full path displayed by `git worktree list` (although you can disable
that with the `-u/--no-user` option, likely set as a [default
option](#default-options)).
Note if you have `-F/--fuzzy` enabled but you don't want to also use that for
git worktree selection then you can disable it with the `-G/--no-fuzzy-git`
option.
#### Relative Git Worktree Directories
The `git worktree list` command displays absolute directory paths, and cdhist
does also by default, but many users prefer them displayed as shorter relative
paths. The Git worktree command does not provide this but you can enable it in
cdhist by adding the `-r/--git-relative` option, e.g:
```sh
$ cd -gr
3 ../development 9796714 [development]
2 ../milestone1 bc921b8 [milestone1]
1 ../test e6d965a [test]
0 . f76b8e0 [main]
Select index [or <enter> to quit]:
```
Most likely you will want to set this as your default so do that by adding
`-r/--git-relative` as a [default option](#default-options).
#### Git Worktree Functionality Alone
Some users may want the git worktree functionality provided by cdhist but are
not interested in the standard `cd` history 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 the first
argument to the `cdhist` command in your shell initialization code. E.g, to use
the command name `wt` for git worktree functionality (only), add the following
in your `~/.bashrc` or `~/.zshrc` file:
```sh
source <(cdhist -i "wt -g")
```
Then log out/in. Type `wt` to list the git worktrees and be prompted to select
the directory etc. Of course, you can define this `wt` command in parallel to
using cdhist for your `cd` command if you want.
## Command Line Usage
Type `cdhist -h` to view the usage summary:
```
usage: cdhist [-h] [-i] [-l] [-m SIZE] [-n NUM_LINES] [-p] [-a] [-g] [-r]
[-R] [-u] [-U] [-F FUZZY] [-G] [-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:
-h, --help show help/usage
-i, --init output shell initialization code. Optionally specify
alternative command name as argument, default="cd"
-l, --list just list directory history
-m, --size SIZE maximum size of directory history (default=200)
-n, --num-lines NUM_LINES
limit output to specified number of lines
-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)
-F, --fuzzy FUZZY use specified fuzzy finder program to select directory
from list
-G, --no-fuzzy-git do not use fuzzy finder for git worktree selection
-L, --follow-links follow symbolic links (default=true)
-P, --follow-physical
follow links to physical directory
-V, --version just output cdhist version
```
## Limitations
Regular `cd`, e.g. as provided by the bash builtin, offers some esoteric
command line options such as `-e` and `-@`, and shell options such as `autocd`,
`cdspell`, `cdable_vars`. These rarely used options are not supported by
cdhist.
## License
Copyright (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 at <http://www.gnu.org/licenses/> for more details.
[pipx]: https://github.com/pypa/pipx
[pipxu]: https://github.com/bulletmark/pipxu
[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools
[fzf]: https://github.com/junegunn/fzf
[fzy]: https://github.com/jhawthorn/fzy
[television]: https://github.com/alexpasmantier/television
Raw data
{
"_id": null,
"home_page": null,
"name": "cdhist",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bash, zsh, cd, fzf, git, worktree",
"author": null,
"author_email": "Mark Blakeney <mark.blakeney@bullet-systems.net>",
"download_url": "https://files.pythonhosted.org/packages/de/b3/8e74459c6be74c78a705eed2cb0055e8e2c0ef0a5df0d6766294aca00743/cdhist-4.1.tar.gz",
"platform": null,
"description": "## CDHIST - Linux Directory History\n[](https://pypi.org/project/cdhist/)\n[](https://aur.archlinux.org/packages/cdhist/)\n\n[cdhist](http://github.com/bulletmark/cdhist) is a utility which provides a\nLinux shell **cd history** directory stack. A shell `cd` wrapper function calls\ncdhist to intercept your typed `cd` command and maintain an ordered stack of\nall directories you have previously visited which can be listed and quickly\nnavigated to.\n\n[cdhist](http://github.com/bulletmark/cdhist) can also be used with a fuzzy\nfinder (such as [`fzf`][fzf]) to fuzzy search and select on previously visited\ndirectories, and can be used to easily `cd` between [`git\nworktree`](https://git-scm.com/docs/git-worktree) directories. See the sections\nbelow about [Fuzzy Finder Integration](#fuzzy-finder-integration) and [Git\nWorktree Integration](#git-worktree-integration).\n\nThe latest version and documentation is available at\nhttp://github.com/bulletmark/cdhist.\n\n## Example Usage\n\nUse the `cd` command to change directory as normal:\n\n```sh\n$ cd /tmp\n$ cd /etc\n$ cd /usr/share/doc\n$ cd /boot/loader\n$ cd ~/etc\n$ cd\n```\n\nAt any point you can use the `cd --` command to list all your previously\nvisited directories and be prompted for one to select and `cd` to:\n\n```\n$ cd --\n 6 ...\n 5 /tmp\n 4 /etc\n 3 /usr/share/doc\n 2 /boot/loader\n 1 ~/etc\n 0 ~\nSelect index [or <enter> to quit]: 3\n$ pwd\n/usr/share/doc\n```\n\nThat's it! The above is all you really need to know. Instead of having to type\nthe directory name you merely enter it's index. The directories are displayed\nmost recently visited last, without duplicates. Index 0 is the current\ndirectory, index 1 is the previous, index 2 is the second previous, up to a\nuser configurable number (default 200).\n\nIf you prefer a more modern approach you can use a fuzzy finder such as\n[`fzf`][fzf], or [`fzy`][fzy], or [`television`][television] to show and select\nfrom the list, instead of a simple index prompt. See the section on [Fuzzy\nFinder Integration](#fuzzy-finder-integration) below.\n\nOther available commands and options are:\n\nList the current stack and its indices (without prompting):\n\n```sh\n$ cd -l\n```\n\nChange immediately to directory corresponding to stack index 4:\n\n```sh\n$ cd -4\n```\n\nSearch back through stack for directory containing \"string\" and `cd`\nthere:\n\n```sh\n$ cd -/string\n```\n\nNote, you can also type `string` at the `cd --` prompt to search.\n\nShow help/usage:\n\n```sh\n$ cd -h\n```\n\n## Installation\n\nArch users can install [cdhist from the\nAUR](https://aur.archlinux.org/packages/cdhist/) and skip to the next section.\n\nPython 3.8 or later is required. Note [cdhist is on\nPyPI](https://pypi.org/project/cdhist/) so the easiest way to install it is to\nuse [`uv tool`][uvtool] (or [`pipx`][pipx] or [`pipxu`][pipxu]).\n\n```sh\n$ uv tool install cdhist\n```\n\nTo upgrade:\n\n```sh\n$ uv tool upgrade cdhist\n```\n\nTo uninstall:\n\n```sh\n$ uv tool uninstall cdhist\n```\n\n## Setup\n\nA user who wants to use the cdhist facility should add the following line to\ntheir `~/.bashrc` or `~/.zshrc` file. Ensure it is added after where your PATH\nis set up so that the command `cdhist` can be found. This creates the `cd`\nwrapper command in your interactive shell session as a tiny function.\n\n```sh\nsource <(cdhist -i)\n```\n\nThen log out and back in again to activate the new `cd` function. Note assuming\na normal `.bashrc` environment, this will alias your `cd` command in your\ninteractive terminal session only. The remapped `cd` will not be invoked by any\nprograms or scripts you run, or for other users etc.\n\n### Alternative Command Name\n\nSome people may prefer not to alias their real `cd` command to this utility and\njust use an alternative unique command name. To do this, simply add your\ndesired command name as the first argument to the `cdhist -i` option in your\nshell initialization code. E.g, to use the command name `xd` rather than `cd`,\nuse the following in your `~/.bashrc` or `~/.zshrc` file:\n\n```sh\nsource <(cdhist -i xd)\n```\n\nThen log out/in, and then use `xd /tmp` to change dir, `xd --` to see and\nselect directories, etc.\n\n### Default Options\n\nYou can set default cdhist options by appending options in the shell\ninitialization code, e.g:\n\n```sh\nsource <(cdhist -i \"cd -arm 100\")\n```\n\nThe above sets `-a (--purge-always)`, '' `-r (--git-relative)`, and `-m\n(--size) 100` options as defaults for your `cd` command.\n\nNote you can use multiple source lines to define multiple commands. E.g. define\none alias for your `cd` command, and another alias for your git worktree\ncommand (e.g. `wt`). Both can have different cdhist options.\n\nThe following options are sensible candidates to set as default options:\n`-m/--size`, `-a/--purge-always`, `-g/--git`, `-r/--git-relative`,\n`-u/--no-user`, `-F/--fuzzy`, `-G/--no-fuzzy-git`.\n\nNote if you set `-r/--git-relative` or `-u/--no-user` options as default then\noptions `-R/--no-git-relative` and `-U/--user` exist to allow you to\ntemporarily override those defaults via the command line.\n\n### Fuzzy Finder Integration\n\nAny of the popular command line fuzzy search finders such as [`fzf`][fzf], or\n[`fzy`][fzy], or [`television`][television] can be used with `cdhist`.\n\nE.g. to use [`fzf`][fzf]:\n\n```sh\nsource <(cdhist -i \"cd -F fzf\")\n```\n\nOr, to use [`television`][television]:\n\n```sh\nsource <(cdhist -i \"cd -F \\\"tv --no-preview\\\"\")\n```\n\nNow when you type `cd --` you will be prompted with a list of directories via\nyour fuzzy finder so you can search for a directory to select by fuzzy text\nmatching.\n\nIn the following description, [`fzf`][fzf] will be used as it is by far the\nmost popular fuzzy finder and the one used by the author. When you set up `fzf`\n[shell integration](https://junegunn.github.io/fzf/shell-integration/) then you\ncan use the following terminal key bindings for `fzf`:\n\n- `CTRL+t` to select files,\n- `CTRL+r` to select commands,\n- `ATL+c` to select directories.\n\nHowever, I never use the last `ATL+c` function because it lists directories\nonly under the current directory whereas I am much more interested in listing\nall directories I have previously visited, i.e. those maintained by cdhist. So\nI disable that function in `fzf` by setting the `FZF_ALT_C_COMMAND` to an empty\nstring before I source `fzf` in my `.bashrc` when [setting `fzf` up](https://junegunn.github.io/fzf/shell-integration/#setting-up-shell-integration).\n\nThen I set the following shell key binding in my `~/.inputrc` file (need to\nrestart your shell to activate):\n\n```sh\n\"\\ec\": \"cd --\\n\"\n```\n\nNow pressing `ALT+c` invokes cdhist to bring up the `fzf` list of my previously\nvisited directories. Alternately, use `ALT+d` for cdhist and keep `ALT+c` for\nthe default `fzf` search behavior.\n\nYou also have the choice of keeping the standard `cd --` command to work with\nsimple index selection, and map a different cdhist command name to use with\n`ALT+c` only for the fuzzy finder. To do this, add the following 2 lines to your\n`~/.bashrc` or `~/.zshrc` file:\n\n```sh\nsource <(cdhist -i)\nsource <(cdhist -i \"cdfuzzy -F fzf\")\n```\n\nAnd then in your `~/.inputrc`:\n\n```\n\"\\ec\": \"cdfuzzy --\\n\"\n```\n\nNote all the above assumes you have the fuzzy finder somewhere in your PATH. If\nyou don't then just specify the full path, e.g:\n\n```sh\nsource <(cdhist -i \"cd -F /path-to/fzf\")\n```\n\n### GIT Worktree Integration\n\n[cdhist](http://github.com/bulletmark/cdhist) can be used to easily `cd`\nbetween [git worktree](https://git-scm.com/docs/git-worktree)\ndirectories. You use the `cd -g` command to list all your worktrees and\nbe prompted for one to select, and then you will be switched to the\nassociated directory, and it will be added to your `cd` history.\n\n```sh\n# Current directory:\n$ pwd\n/home/mark/src/myprog\n\n# List worktrees using standard git command:\n$ git worktree list\n/home/mark/src/myprog f76b8e0 [main]\n/home/mark/src/development 9796714 [development]\n/home/mark/src/milestone1 bc921b8 [milestone1]\n/home/mark/src/test e6d965a [test]\n\n# Alternately, use cdhist to list worktrees and choose one to navigate to:\n$ cd -g\n 3 ~/src/development 9796714 [development]\n 2 ~/src/milestone1 bc921b8 [milestone1]\n 1 ~/src/test e6d965a [test]\n 0 ~/src/myprog f76b8e0 [main]\nSelect index [or <enter> to quit]: 2\n\n$ pwd\n/home/mark/src/milestone1\n\n# Or, use cdhist to navigate to worktree dir for given branch name or\n# commit:\n$ cd -g main\n$ pwd\n/home/mark/src/myprog\n```\n\nInstead of having to type the full git repository directory name you merely are\nprompted with a list and enter it's index. Or just directly enter the branch\nname (or commit hash). The directories are displayed in the same order as the\noutput of the `git worktree list` command, except that the git directory\ncorresponding to the current working directory is shown first (index 0)\nconsistent with how the current directory is shown at index 0 for normal cd\nhistory and thus conveniently showing you which git worktree you are currently\nin which `git worktree list` unfortunately does not show.\n\nIn you enter text instead of an index, you only need to enter as much of the\nbranch name, or commit hash, as needed to be unique. Note that `cd -g` nicely\npresents paths based from your HOME directory with a tilde (`~`) unlike the\nlonger full path displayed by `git worktree list` (although you can disable\nthat with the `-u/--no-user` option, likely set as a [default\noption](#default-options)).\n\nNote if you have `-F/--fuzzy` enabled but you don't want to also use that for\ngit worktree selection then you can disable it with the `-G/--no-fuzzy-git`\noption.\n\n#### Relative Git Worktree Directories\n\nThe `git worktree list` command displays absolute directory paths, and cdhist\ndoes also by default, but many users prefer them displayed as shorter relative\npaths. The Git worktree command does not provide this but you can enable it in\ncdhist by adding the `-r/--git-relative` option, e.g:\n\n```sh\n$ cd -gr\n 3 ../development 9796714 [development]\n 2 ../milestone1 bc921b8 [milestone1]\n 1 ../test e6d965a [test]\n 0 . f76b8e0 [main]\nSelect index [or <enter> to quit]:\n```\n\nMost likely you will want to set this as your default so do that by adding\n`-r/--git-relative` as a [default option](#default-options).\n\n#### Git Worktree Functionality Alone\n\nSome users may want the git worktree functionality provided by cdhist but are\nnot interested in the standard `cd` history functionality, or alternately, want\nto use a completely separate command for the git worktree functionality. To do\nthis, simply add your desired command name and the git option the first\nargument to the `cdhist` command in your shell initialization code. E.g, to use\nthe command name `wt` for git worktree functionality (only), add the following\nin your `~/.bashrc` or `~/.zshrc` file:\n\n```sh\nsource <(cdhist -i \"wt -g\")\n```\n\nThen log out/in. Type `wt` to list the git worktrees and be prompted to select\nthe directory etc. Of course, you can define this `wt` command in parallel to\nusing cdhist for your `cd` command if you want.\n\n## Command Line Usage\n\nType `cdhist -h` to view the usage summary:\n\n```\nusage: cdhist [-h] [-i] [-l] [-m SIZE] [-n NUM_LINES] [-p] [-a] [-g] [-r]\n [-R] [-u] [-U] [-F FUZZY] [-G] [-L] [-P] [-V]\n [directory]\n\nA Linux shell directory stack \"cd history\" function.\n\npositional arguments:\n directory directory (or branch for git worktree) to cd to, or\n \"--\" to list history and prompt, or \"-n\" for n'th\n entry in list or \"-/<string>\" to match for \"string\" in\n dir\n\noptions:\n -h, --help show help/usage\n -i, --init output shell initialization code. Optionally specify\n alternative command name as argument, default=\"cd\"\n -l, --list just list directory history\n -m, --size SIZE maximum size of directory history (default=200)\n -n, --num-lines NUM_LINES\n limit output to specified number of lines\n -p, --purge just purge non-existent directories from history\n -a, --purge-always always purge non-existent directories every write\n -g, --git show git worktree directories instead\n -r, --git-relative show relative git worktree paths instead of absolute\n -R, --no-git-relative\n do not show relative git worktree paths (default)\n -u, --no-user do not substitute \"~\" for home directory\n -U, --user do substitute \"~\" for home directory (default)\n -F, --fuzzy FUZZY use specified fuzzy finder program to select directory\n from list\n -G, --no-fuzzy-git do not use fuzzy finder for git worktree selection\n -L, --follow-links follow symbolic links (default=true)\n -P, --follow-physical\n follow links to physical directory\n -V, --version just output cdhist version\n```\n\n## Limitations\n\nRegular `cd`, e.g. as provided by the bash builtin, offers some esoteric\ncommand line options such as `-e` and `-@`, and shell options such as `autocd`,\n`cdspell`, `cdable_vars`. These rarely used options are not supported by\ncdhist.\n\n## License\n\nCopyright (C) 2010 Mark Blakeney. This program is distributed under the\nterms of the GNU General Public License.\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or any later\nversion.\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License at <http://www.gnu.org/licenses/> for more details.\n\n[pipx]: https://github.com/pypa/pipx\n[pipxu]: https://github.com/bulletmark/pipxu\n[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools\n[fzf]: https://github.com/junegunn/fzf\n[fzy]: https://github.com/jhawthorn/fzy\n[television]: https://github.com/alexpasmantier/television\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Program to provide a Linux cd history directory stack",
"version": "4.1",
"project_urls": {
"Homepage": "https://github.com/bulletmark/cdhist"
},
"split_keywords": [
"bash",
" zsh",
" cd",
" fzf",
" git",
" worktree"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31d9dbc0f5a16d0125882c30bfad2722016a7a627b841b697b619412c9a8634d",
"md5": "3a410840c292867b9f61603dc68a4aef",
"sha256": "9632948056aff4540eb73a731be166ed0785fe695b244af6690d1913dc8d5781"
},
"downloads": -1,
"filename": "cdhist-4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a410840c292867b9f61603dc68a4aef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13219,
"upload_time": "2025-01-31T22:48:36",
"upload_time_iso_8601": "2025-01-31T22:48:36.841707Z",
"url": "https://files.pythonhosted.org/packages/31/d9/dbc0f5a16d0125882c30bfad2722016a7a627b841b697b619412c9a8634d/cdhist-4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "deb38e74459c6be74c78a705eed2cb0055e8e2c0ef0a5df0d6766294aca00743",
"md5": "e69a5be040a8d5a46f6d3c9c5ae652eb",
"sha256": "5ad355025ef312b6c08ffe7717af0c173a4572662b148bd882916c4520675b4d"
},
"downloads": -1,
"filename": "cdhist-4.1.tar.gz",
"has_sig": false,
"md5_digest": "e69a5be040a8d5a46f6d3c9c5ae652eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17154,
"upload_time": "2025-01-31T22:48:38",
"upload_time_iso_8601": "2025-01-31T22:48:38.178660Z",
"url": "https://files.pythonhosted.org/packages/de/b3/8e74459c6be74c78a705eed2cb0055e8e2c0ef0a5df0d6766294aca00743/cdhist-4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-31 22:48:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bulletmark",
"github_project": "cdhist",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cdhist"
}
