---
id: path
title: Path
sidebar_label: Path
---

## What

Display the current path.

## Sample Configuration

import Config from "@site/src/components/Config.js";

<Config
  data={{
    type: "path",
    style: "powerline",
    powerline_symbol: "\uE0B0",
    foreground: "#ffffff",
    background: "#61AFEF",
    options: {
      style: "folder",
      mapped_locations: {
        "C:\\temp": "\ue799",
      },
    },
  }}
/>

## Options

| Name                        |    Type    |  Default   | Description                                                                                                      |
| --------------------------- | :--------: | :--------: | ---------------------------------------------------------------------------------------------------------------- |
| `folder_separator_icon`     |  `string`  |    `/`     | the symbol to use as a separator between folders                                                                 |
| `folder_separator_template` |  `string`  |            | the [template][templates] to use as a separator between folders                                                  |
| `home_icon`                 |  `string`  |    `~`     | the icon to display when at `$HOME`                                                                              |
| `folder_icon`               |  `string`  |    `..`    | the icon to use as a folder indication                                                                           |
| `windows_registry_icon`     |  `string`  |  `\uF013`  | the icon to display when in the Windows registry                                                                 |
| `style`                     |   `enum`   | `agnoster` | how to display the current path                                                                                  |
| `mixed_threshold`           |  `number`  |    `4`     | the maximum length of a path segment that will be displayed when using `Mixed`                                   |
| `max_depth`                 |  `number`  |    `1`     | maximum path depth to display before shortening when using `agnoster_short`                                      |
| `max_width`                 |   `any`    |    `0`     | maximum path length to display when using `powerlevel` or `agnoster`, can leverage [templates]                   |
| `hide_root_location`        | `boolean`  |  `false`   | hides the root location if it doesn't fit in the last `max_depth` folders when using `agnoster_short`            |
| `cycle`                     | `[]string` |            | a list of color overrides to cycle through to colorize the individual path folders, e.g. `[ "#ffffff,#111111" ]` |
| `cycle_folder_separator`    | `boolean`  |  `false`   | colorize the `folder_separator_icon` as well when using a cycle                                                  |
| `folder_format`             |  `string`  |    `%s`    | format to use on individual path folders                                                                         |
| `edge_format`               |  `string`  |    `%s`    | format to use on the first and last folder of the path                                                           |
| `left_format`               |  `string`  |    `%s`    | format to use on the first folder of the path - defaults to `edge_format`                                        |
| `right_format`              |  `string`  |    `%s`    | format to use on the last folder of the path - defaults to `edge_format`                                         |
| `gitdir_format`             |  `string`  |            | format to use for a Git root directory, including linked worktrees                                                |
| `display_cygpath`           | `boolean`  |  `false`   | display the Cygwin style path using `cygpath -u $PWD`                                                            |
| `display_root`              | `boolean`  |  `false`   | display the root `/` on Unix systems                                                                             |
| `dir_length`                |  `number`  |    `1`     | the length of the directory name to display when using `fish`                                                    |
| `full_length_dirs`          |  `number`  |    `1`     | indicates how many full length directory names should be displayed when using `fish`                             |

## Mapped Locations

Allows you to override a location with an icon/string.
It validates if the current path **starts with the specific elements** and replaces it with the icon/string if there's a match.
To avoid issues with nested overrides, Oh My Posh will sort the list of mapped locations before doing a replacement.

| Name                            |    Type   | Default | Description                                                                                       |
| ------------------------------- | :-------: | :-----: | ------------------------------------------------------------------------------------------------- |
| `mapped_locations_enabled`      | `boolean` |  `true` | replace known locations in the path with the replacements before applying the style               |
| `mapped_locations`              |  `object` |         | custom glyph/text for specific paths. Works regardless of the `mapped_locations_enabled` setting  |
| `mapped_locations_regex_expand` | `boolean` | `false` | expand `$1`, `${name}`, etc. in a `re:` replacement value, see [below](#expanding-capture-groups) |

For example, to swap out `C:\Users\Leet\GitHub` with a GitHub icon, you can do the following:

<Config
  data={{
    mapped_locations: {
      "C:\\Users\\Leet\\GitHub": "\uF09B",
    },
  }}
/>

### How it works

- To make mapped locations work cross-platform, use `/` as the path separator, Oh My Posh will
  automatically match effective separators based on the running operating system.
- If you want to match all child directories, you can use `*` as a wildcard, for example:
  `"C:/Users/Bill/*": "$"` will turn `C:/Users/Bill/Downloads` into `$/Downloads` but leave `C:/Users/Bill` unchanged.
- The character `~` at the start of a mapped location will match the user's home directory.
- The match is _case-insensitive on Windows and macOS_, but case-sensitive on other operating systems. This means that for
  user Bill, who has a user account `Bill` on Windows and `bill` on Linux, `~/Foo` might match
  `C:\Users\Bill\Foo` or `C:\Users\Bill\foo` on Windows but only `/home/bill/Foo` on Linux.

:::warning
To prevent mangling path elements, if you use any text style tags (e.g., `<lightGreen>...</>`) in replacement values,
you should avoid using a chevron character (`<`/`>`) in the `folder_separator_icon` property, and vice versa.
:::

### Using regular expressions

For more complicated cases, you can use the `re:` prefix to use a regular expression with a capture group for matching.
This uses Golang's [regexp] package, so you can use any of the [supported syntax][regexp]. The replacement value will be the first capture group,
subsequent groups will be ignored.

For example, `"re:(C:/[0-9]+/Foo)": "#"` will match `C:\123\Foo\Bar` and replace it with `#\Bar`. The path used for matching
will always use `/`, regardless of the operating system, allowing cross platform matching.

Same as for standard replacements, the match is case insensitive on Windows and WSL mounted drives, but case-sensitive on
other operating systems.

### Expanding capture groups

By default, only the first capture group is used, and its matched text is replaced as-is; additional groups, whether
positional or named, are ignored. Set `mapped_locations_regex_expand` to `true` to reference capture groups in the
replacement value instead, using `$1`, `$2`, or `${name}` for named groups. When enabled, the full regex match (not
just the first capture group) is replaced with the expanded value.

For example, to display the repository name instead of the Git worktree folder, you can capture it in a named group
and reference it in the replacement:

<!-- markdownlint-disable MD033 MD049 -->

<Config
  data={{
    options: {
      mapped_locations_regex_expand: true,
      mapped_locations: {
        "re:(.*/GitHub/(?P<repo>.*)\\.worktrees/.*)": "\uF09B ${repo}",
      },
    },
  }}
/>

<!-- markdownlint-enable MD033 MD049 -->

This turns `~/GitHub/oh-my-posh.worktrees/feature-branch` into the GitHub icon followed by `oh-my-posh`.

## Style

Style sets the way the path is displayed. Based on previous experience and popular themes, there are 10 flavors.

- `agnoster`
- `agnoster_full`
- `agnoster_short`
- `agnoster_left`
- `full`
- `folder`
- `mixed`
- `letter`
- `unique`
- `powerlevel`
- `fish`

### Agnoster

Renders each intermediate folder as the `folder_icon` separated by the `folder_separator_icon`.
The first and the last (current) folder name are always displayed as-is.

### Agnoster Full

Renders each folder name separated by the `folder_separator_icon`.

### Agnoster Short

When more than `max_depth` levels deep, it renders one `folder_icon` (if `hide_root_location` is `false`,
which means the root folder does not count for depth) followed by the names of the last `max_depth` folders,
separated by the `folder_separator_icon`.

### Agnoster Left

Renders each folder as the `folder_icon` separated by the `folder_separator_icon`.
Only the first folder name and its child are displayed in full.

### Full

Display the current working directory as a full string with each folder separated by the `folder_separator_icon`.

### Folder

Display the name of the current folder.

### Mixed

Works like `agnoster`, but for any intermediate folder name that is short enough, it will be displayed as-is.
The maximum length for the folders to display is governed by the `mixed_threshold` property.

### Letter

Works like `agnoster_full`, but will write every folder name using the first letter only, except when the folder name
starts with a symbol or icon. Specially, the last (current) folder name is always displayed in full.

- `folder` will be shortened to `f`
- `.config` will be shortened to `.c`
- `__pycache__` will be shortened to `__p`
- `➼ folder` will be shortened to `➼ f`

### Unique

Works like `letter`, but will make sure every folder name is the shortest unique value.

The uniqueness refers to the displayed path, so `C:\dev\dev\dev\development` will be displayed as
`C\d\de\dev\development` (instead of `C\d\d\d\development` for `Letter`). Uniqueness does **not** refer to other
folders at the same level, so if `C:\projectA\dev` and `C:\projectB\dev` exist, then both will be displayed as
`C\p\dev`.

### Powerlevel

Works like `unique`, but will stop shortening when `max_width` is reached.

### Fish

Works like `letter`, but will display the first `dir_length` characters of each folder name, except for the last
number of folders specified by `full_length_dirs`, which will be displayed in full. Inspired by the Fish shell PWD.

## Template ([info][templates])

:::note default template

```template
 {{ .Path }}
```

:::

### Properties

| Name          | Type       | Description                                                                                                                                                            |
| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.Path`       | `string`   | the current directory (based on the `style` property)                                                                                                                  |
| `.Parent`     | `string`   | the current directory's parent folder which ends with a path separator (designed for use with style `folder`, it is empty if `.Path` contains only one single element) |
| `.RootDir`    | `boolean`  | true if we're at the root directory (no parent)                                                                                                                        |
| `.Location`   | `string`   | the current directory (raw value)                                                                                                                                      |
| `.StackCount` | `int`      | the stack count                                                                                                                                                        |
| `.Writable`   | `boolean`  | is the current directory writable by the user or not                                                                                                                   |
| `.Format`     | `function` | format any path based on the segment's settings (e.g. `{{ .Format .Segments.Git.RelativeDir }}`)                                                                       |

[templates]: /docs/configuration/templates
[regexp]: https://pkg.go.dev/regexp/syntax
