Alacritty Setup for Git Bash on Windows

Summary

This RFD documents a durable baseline for using Alacritty as the primary terminal on Windows. It complements the broader Windows workflow guidance in 0004, the Git Bash-oriented SSH guidance in 0005, and the sidebar-wrapper prototype plan in 0007.

The determination is to:

• keep the Alacritty config at %AppData%\alacritty\alacritty.toml,
• launch Git Bash directly from Alacritty,
• use MesloLGS NF as the terminal font,
• keep a mostly opaque dark theme with modest padding,
• preserve clipboard-friendly key bindings,
• prefer configuration that behaves predictably for interactive development.

This is the preferred baseline because it provides a fast terminal with a stable shell choice, reliable Nerd Font glyph coverage, and minimal visual friction during day-to-day engineering work.

Problem

A Windows development environment often accumulates multiple terminals, inconsistent shells, and partially configured fonts. That leads to issues such as:

• prompt glyphs rendering incorrectly,
• shell behavior differing between terminal apps,
• opening in the wrong working directory,
• copy and paste shortcuts not matching expectations,
• visual distractions from excessive opacity, padding, or bell behavior,
• difficulty reproducing the same setup on a fresh machine.

If the terminal is part of the core development loop, the configuration should be explicit and portable rather than implicit or left to defaults.

Constraints and goals

The desired setup should:

• work well on Windows,
• treat Git Bash as the interactive shell,
• support patched Nerd Font glyphs for modern prompts,
• open in a useful default development directory,
• preserve familiar copy and paste key bindings,
• stay easy to edit and reload,
• avoid depending on unsupported environment-variable expansion inside Alacritty config values.

Applied configuration

Create or update %AppData%\alacritty\alacritty.toml with the following baseline:

[general]
## Reload config on changes
live_config_reload = true
## NOTE: env vars like %APPDATA% or ${env:APPDATA} do NOT work here

working_directory = "C:\\Users\\icleary\\Development"

## Import themes.
#  NOTE: You must clone the git repository or download the themes/ directory,
#  and put it at the location in the import statement.
#  <https://github.com/alacritty/alacritty-theme>
# import = ["~/.config/alacritty/themes/atom_one_dark.toml"]

[env]
TERM = "xterm-256color"

[window]
## Set CWD as window title
dynamic_title = true
## Ignored when dynamic_title = true
title = "Alacritty"

## Fullscreen, Maximized, Windowed, SimpleFullscreen
startup_mode = "Windowed"

## How transparent the window is; 0.0 to 1.0
opacity = 0.95

## Add additional padding evenly around terminal content
dynamic_padding = true
padding.x = 4
padding.y = 0

## Full, None, Transparent, Buttonless
decorations = "Full"
## Dark, Light
decorations_theme_variant = "Dark"

## Default terminal width
dimensions.columns = 100
## Default terminal height
dimensions.lines = 25

## On-screen dimensions for window placement on open
position.x = 300
position.y = 150

[scrolling]
history = 1000
multiplier = 3

[terminal]
shell = { program = "C:\\Program Files\\Git\\bin\\bash.exe" }

[font]
size = 12

offset.x = 0
offset.y = 0

glyph_offset.x = 0
glyph_offset.y = 0

normal.family = "MesloLGS NF"
normal.style = "Regular"

bold.family = "MesloLGS NF"
bold.style = "Bold"

italic.family = "MesloLGS NF"
italic.style = "Italic"


[colors]
draw_bold_text_with_bright_colors = true

[colors.primary]
background = "0x1e1e2e"
foreground = "0xc0caf5"

[colors.normal]
black = "0x1e1e2e"
red = "0xf7768e"
green = "0x9ece6a"
yellow = "0xe0af68"
blue = "0x7aa2f7"
magenta = "0xbb9af7"
cyan = "0x7dcfff"
white = "0xa9b1d6"

[colors.bright]
black = "0x414868"
red = "0xf7768e"
green = "0x9ece6a"
yellow = "0xe0af68"
blue = "0x7aa2f7"
magenta = "0xbb9af7"
cyan = "0x7dcfff"
white = "0xc0caf5"

[colors.cursor]
text = "0x1e1e2e"
cursor = "0xc0caf5"


[bell]
## "Ease", "EaseOut", "EaseOutSine", "EaseOutQuad",
#  "EaseOutCubic", "EaseOutQuart", "EaseOutQuint",
#  "EaseOutExpo", "EaseOutCirc", "Linear"
animation = "EaseOutExpo"
color     = "#C0C5CE"
## Command to run when bell is rung
command   = "None"
## Time in milliseconds. 0=disabled
duration  = 0

[selection]
save_to_clipboard = true
semantic_escape_chars = ",│`|:\"' ()[]{}<>\t"


[cursor]
## Time in milliseconds between blinks, default 750
blink_interval = 650
## Time in seconds for cursor to "hold" its blink, default 5
blink_timeout = 5
## Thickness of cursor relative to cell width. 0.0 to 1.0, default 0.15
thickness = 0.25
## Render cursor as a hollow box when window loses focus
unfocused_hollow = true
## Block, Beam, Underline
style.shape = "Block"
## Never, Off, On, Always
style.blinking = "On"

[[keyboard.bindings]]
action = "Paste"
key    = "V"
mods   = "Control|Shift"

[[keyboard.bindings]]
action = "Copy"
key    = "C"
mods   = "Control|Shift"

[[keyboard.bindings]]
action = "ScrollPageUp"
key    = "PageUp"
mods   = "Shift"

[[keyboard.bindings]]
action = "ScrollPageDown"
key    = "PageDown"
mods   = "Shift"

[[keyboard.bindings]]
action = "ScrollToTop"
key    = "Home"
mods   = "Shift"

[[keyboard.bindings]]
action = "ScrollToBottom"
key    = "End"
mods   = "Shift"

[[keyboard.bindings]]
key = "Return"
mods = "Control|Shift"
action = "SpawnNewInstance"

[[keyboard.bindings]]
action = "IncreaseFontSize"
key = "Equals"
mods = "Control"

[[keyboard.bindings]]
action = "DecreaseFontSize"
key = "Minus"
mods = "Control"

[[keyboard.bindings]]
action = "ClearLogNotice"
key = "L"
mods = "Control"

[[keyboard.bindings]]
chars = "\f"
key = "L"
mods = "Control"

[mouse]
hide_when_typing = true

[[mouse.bindings]]
action = "PasteSelection"
mouse = "Middle"

[debug]
highlight_damage   = false
log_level          = "Warn"
persistent_logging = false
print_events       = false
render_timer       = false

[[hints.enabled]]
regex = "[^ ]+\\.rs:\\d+:\\d+"
command = { program = "code", args = [ "--goto" ] }
mouse = { enabled = true }

Font installation

Install MesloLGS NF manually so prompt glyphs and other Nerd Font symbols render correctly.

Download and install these four font files:

1. MesloLGS NF Regular.ttf
2. MesloLGS NF Bold.ttf
3. MesloLGS NF Italic.ttf
4. MesloLGS NF Bold Italic.ttf

For each file:

• double-click the .ttf file,
• click Install.

This makes MesloLGS NF available to Windows applications, including Alacritty.

Why these settings

Git Bash as the shell

[terminal]
shell = { program = "C:\\Program Files\\Git\\bin\\bash.exe" }

This keeps the terminal aligned with a Git-for-Windows workflow. That matters because shell behavior, path handling, SSH usage, and startup configuration are easier to reason about when the terminal always opens the same shell family.

Live config reload

[general]
live_config_reload = true

This makes iteration faster when tuning the terminal. A config change can be tested immediately without fully rebuilding the environment around it.

Explicit working directory

working_directory = "C:\\Users\\icleary\\Development"

Opening in a development root removes a small but repeated source of friction. It also makes the intended default location explicit instead of relying on launcher-specific behavior.

MesloLGS NF font family

[font]
normal.family = "MesloLGS NF"

This is the critical piece for correct prompt and symbol rendering. If the font is missing, the rest of the terminal can appear functional while still degrading the prompt and other glyph-heavy tooling.

Moderate transparency and compact spacing

The chosen opacity, dimensions, and padding aim for readability without making the terminal feel heavy or cramped. The values are opinionated, but they are still conservative enough to serve as a practical baseline.

Clipboard and navigation bindings

The bindings prioritize terminal ergonomics that are predictable on Windows:

• Ctrl+Shift+C copies,
• Ctrl+Shift+V pastes,
• Shift+PageUp and Shift+PageDown scroll,
• Ctrl+Shift+Enter opens a new Alacritty instance,
• Ctrl+= and Ctrl+- adjust font size.

Verification

Verify the setup with the following checks:

1. open Alacritty,
2. confirm the shell is Git Bash,
3. confirm the window starts in C:\Users\icleary\Development,
4. confirm the prompt renders Nerd Font glyphs correctly,
5. confirm Ctrl+Shift+C and Ctrl+Shift+V behave as expected,
6. confirm Ctrl+Shift+Enter spawns a new instance,
7. confirm saving alacritty.toml reloads the config without restarting the terminal.

A practical shell verification is:

echo "$SHELL"
pwd
printf 'glyph test: %s\n' '  λ'

What not to rely on

Do not rely on environment-variable expansion inside the Alacritty config for this file path. This setup explicitly notes that values such as %APPDATA% or ${env:APPDATA} do not work in the relevant config position. Use explicit Windows paths instead.

Do not assume the font is present just because the config names it. The font must actually be installed in Windows.

Do not assume another terminal app's shell defaults automatically carry over to Alacritty. The shell path should be configured directly.

Troubleshooting

Font looks wrong or prompt glyphs are broken

• Reinstall all four MesloLGS NF font files.
• Confirm the configured family name is exactly MesloLGS NF.
• Close and reopen Alacritty after font installation if Windows has not refreshed font availability yet.

Alacritty opens in the wrong shell

• Confirm Git for Windows is installed.
• Confirm C:\Program Files\Git\bin\bash.exe exists.
• If Git is installed elsewhere, update the shell.program path explicitly.

Working directory does not resolve as expected

• Confirm the configured path exists.
• Do not replace it with %USERPROFILE% or similar variables inside this config value.
• Use a fully expanded Windows path.

VS Code file hints do not open

The configured hint handler assumes code is on PATH:

[[hints.enabled]]
command = { program = "code", args = [ "--goto" ] }

If that command fails, install the VS Code shell command or replace it with the correct program path.

Security notes

This configuration is primarily about terminal ergonomics, but a few security-adjacent points are worth keeping explicit:

• the shell path should point to a trusted local Git Bash installation,
• the editor command used in hints should be a trusted executable on PATH,
• persistent logging remains disabled in this baseline,
• disabling bell duration avoids noisy side effects without weakening shell security.

Determination

The preferred Windows Alacritty baseline is to run Git Bash inside Alacritty with MesloLGS NF, explicit paths, a dark theme, and clipboard-oriented key bindings. This keeps the terminal fast, legible, and reproducible across machine rebuilds and new Windows setups.

Future expansion

Likely future additions include:

• theme import management using the Alacritty theme repository,
• documenting tabs or multiplexing strategy alongside Alacritty,
• Windows Terminal versus Alacritty trade-off notes,
• shell startup alignment with dotfiles and prompt tooling.