gitui-org/gitui · error · anyhow::Error

failed to find the home directory

Error message

failed to find the home directory

What it means

start_terminal() canonicalizes the repo's .git path and shortens it under ~ for the terminal window title (gitui (~/...)). dirs::home_dir() returned None: on unix, HOME is unset/empty and the passwd entry could not be used as a fallback; on Windows the user profile folder is unresolvable. Because this runs before the TUI is drawn, the anyhow error aborts startup entirely - despite only being needed for a cosmetic title.

Source

Thrown at src/main.rs:329

		2 => oper.recv(rx_app).map(|e| {
			QueueEvent::AsyncEvent(AsyncNotification::App(e))
		}),
		3 => oper.recv(rx_ticker).map(|_| QueueEvent::Notify),
		4 => oper.recv(rx_notify).map(|()| QueueEvent::Notify),
		5 => oper.recv(rx_spinner).map(|_| QueueEvent::SpinnerUpdate),
		_ => bail!("unknown select source"),
	}?;

	Ok(ev)
}

fn start_terminal(
	buf: Stdout,
	repo_path: &RepoPath,
) -> Result<Terminal> {
	let mut path = repo_path.gitpath().canonicalize()?;
	let home = dirs::home_dir().ok_or_else(|| {
		anyhow!("failed to find the home directory")
	})?;
	if path.starts_with(&home) {
		let relative_part = path
			.strip_prefix(&home)
			.expect("can't fail because of the if statement");
		path = Path::new("~").join(relative_part);
	}

	let mut backend = CrosstermBackend::new(buf);
	backend.execute(crossterm::terminal::SetTitle(format!(
		"gitui ({})",
		path.display()
	)))?;

	let mut terminal = Terminal::new(backend)?;
	terminal.hide_cursor()?;
	terminal.clear()?;

View on GitHub (pinned to 2fa693cb6e)

Solutions

1. Export a valid HOME (export HOME=/home/user) in whatever launches gitui.
2. On Windows ensure USERPROFILE is set in the launching context.
3. Run gitui from a real login shell (bash -l) when the environment cannot be fixed at the source.
4. Upstream: guard the home_dir() lookup and skip the ~-shortening instead of bailing - title cosmetics are not fatal.

Example fix

# before
env -i /usr/bin/gitui   # bails: failed to find the home directory
# after
env -i HOME=$HOME /usr/bin/gitui

// Rust (upstream shape): make shortening optional
let home = dirs::home_dir();
if let Some(h) = home.filter(|h| path.starts_with(h)) {
    path = Path::new("~").join(path.strip_prefix(&h).unwrap());
}

# shell
[ -n "$HOME" ] || echo "gitui will fail: HOME missing"

// Rust
dirs::home_dir().is_some()

When it happens

Trigger: HOME scrubbed or empty in cron, systemd units, docker exec with a minimal env, or su to an account without a passwd entry; Windows service contexts missing USERPROFILE; env -i launches.

Common situations: Launching gitui from service files, CI runners, or sanitized containers; hardened images where the user database is absent or HOME is deliberately cleared.

Related errors

• failed to find os cache dir.
• failed to find os config dir.

AI-assisted analysis of gitui-org/gitui@2fa693cb6e (2026-08-16). Data as JSON: /api/errors/764f230ceb2743f3. Report an issue: GitHub.