# Hash built-in

The hash built-in remembers, forgets, or reports command locations.

## Syntax

- `hash command…`

- `hash -r [command…]`

- `hash [-a]`

- `hash -d user…`

- `hash -dr [user…]`

- `hash -d`

## Description

When executed with commands but without options, the built-in immediately performs command path search and caches commands' full paths.

When executed with the `-r` (`--remove`) option, it removes the paths of commands (or all cached paths if none specified) from the cache.

When executed without options or commands, it prints the currently cached paths to the standard output.

With the `-d` (`--directory`) option, the built-in does the same things to the home directory cache, rather than the command path cache. Cached home directory paths are used in tilde expansion.

## Options

`-a`
`--all`

  Print all cached paths.

  Without this option, paths for built-ins are not printed.

`-d`
`--directory`

  Affect the home directory cache instead of the command path cache.

`-r`
`--remove`

  Remove cached paths.

## Operands

command

  The name of an external command (that does not contain any slash).

user

  A user name.

## Exit status

The exit status of the hash built-in is zero unless there is any error.

## Notes

The shell automatically caches command and directory paths when executing a command or performing tilde expansion, so normally there is no need to use this built-in explicitly to cache paths.

Assigning a value to the `PATH` variable removes all command paths from the cache as if `hash -r` was executed.

The POSIX standard defines the `-r` option only: other options cannot be used in the POSIXly-correct mode.

The hash built-in is a mandatory built-in.