# Bash Git Prompt for Ubuntu 24.04 Server
[![OS](https://img.shields.io/badge/ubuntu-24.04-E95420)](#)
[![Shell](https://img.shields.io/badge/shell-bash-121011)](#)
[![Feature](https://img.shields.io/badge/feature-git_prompt-0078D7)](#)
[![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)

Install Bash Git Prompt on Ubuntu 24.04 server.

> **Note**
> Safe for production use. This tool only modifies your shell prompt and does not change system services.

---

## Why this installer exists

Most Bash Git prompts out there are bloated. You have to install oh-my-zsh, oh-my-bash, or some other framework that drags in far more than you need.

This project is the opposite: a fast, lightweight Git status prompt based purely on Bash and Git's own built-in commands.
No frameworks, no plugins, no bloat.

---

## What this installer does

- Shows current Git branch and live repo status
- Supports **five clean themes** (including Powerline and two-line layouts) switchable in real time
- Displays staged, changed, untracked, stashed, and remote state
- Indicates clean/dirty status immediately
- Lets you customise PS1 inside/outside Git repos centrally
- Works seamlessly over SSH
- Includes an **optional** Nerd Font installer

---

## What this installer does NOT do
It will not stop you from running the script without reading the documentation like there is no tomorrow.
Skip the README, and whatever happens next is your headache, not a bug report.

---

### Prerequisites

Requires **JetBrainsMono Nerd Font Mono** for proper symbol display like shown below.

<p align="left" width="100%">
<img src="https://git.x-files.dk/assets/bgp-symbols.png" alt="Extended Symbols"/>
</p>

---

### Prompt Structure

The default prompt layout is:

```plaintext
<branch git status><working directory>
```

Example output with the default theme:

<p align="center" width="100%">
<img src="https://git.x-files.dk/assets/bgp-gittheme1.png" alt="Default Theme"/>
</p>

And here the default theme with all the bells and whistles:

<p align="center" width="100%">
<img src="https://git.x-files.dk/assets/bgp-gittheme2.png" alt="Default Theme All Icons"/>
</p>

---

### Installation

Clone the repository:

```
git clone https://git.x-files.dk/bash/bash-git-prompt.git ~/.bash-git-prompt
```

Install fonts:

```
cd ~/.bash-git-prompt
./install-fonts.sh
```

## Make it happen

Add the following to your .bashrc file:

```
# Git Prompt Start
if [ -f "$HOME/.bash-git-prompt/bash-git-prompt" ]; then
    export GIT_PROMPT_THEME=1
    source "$HOME/.bash-git-prompt/bash-git-prompt"
fi
# Git Prompt Stop
```

Reload your environment:

```
source ~/.bashrc
```

---

### Switching Themes

Change themes dynamically with:

```
gpchange <theme number>
```

Example:
```
gpchange 3
```

This updates the theme instantly for your current session.

### Available Themes

Preview of all five themes (clean and dirty as well as ahead and behind shown together for comparison):

Branch -> Staged -> Changed -> Untracked -> Stashed -> Ahead -> Behind -> No-Remote -> Conflict -> Dirty -> Clean

<p align="center" width="100%">
<img src="https://git.x-files.dk/assets/bgp-gittheme3.png" alt="All Themes"/>
</p>

> **Note**
> Theme 1, 2 and 3 require **JetBrainsMono Nerd Font Mono** for proper symbol rendering.
> Theme 4 is purely **Unicode** -- no special fonts are needed for proper symbol rendering.
> Theme 5 is **terminal safe** so no special fonts needed for proper symbol rendering.

---

### Terminal Font Setup

Set your terminal to use:
```
JetBrainsMono Nerd Font Mono
```

<p align="center" width="100%">
<img src="https://git.x-files.dk/assets/bgp-gittheme4.png" alt="Terminal Font Settings"/>
</p>

---

## Important note about fonts (SSH users take notice)

The Git prompt uses Nerd Font symbols, but:

**You only need Nerd Fonts installed on your local machine.**
Your terminal emulator on your laptop/workstation renders the symbols, not the server.

If you SSH into the server, the prompt will display correctly as long as your local terminal already has the Nerd Font installed.

If you are installing this on a remote server, you can safely skip the font installer.

---

### Changing the prompt layout

Prompt layout is handled centrally in the script inside the `update_git_prompt()` function.

Each theme controls its own structure:

- Theme 1, 4, and 5 use a single-line prompt
- Theme 2 uses a Powerline-style segmented prompt
- Theme 3 uses a two-line prompt

If you want to customise the prompt layout, edit the relevant theme block inside `update_git_prompt()`.

This keeps icons, colours, and layout clearly separated and avoids breaking other themes.

---

### Customizing the prompt outside Git repositories

When this script is loaded, it manages the shell prompt (`PS1`) dynamically so it can switch between Git and non-Git directories.

As long as the script is loaded, **it owns PS1**.  
Any manual `PS1` settings in `.bashrc` will normally have no visible effect, because the prompt is rebuilt automatically. Nothing breaks — the Git prompt simply takes precedence.

If you want to change how the prompt looks **outside Git repositories**, adjust the variables in the script shown below.

#### Outside Git repository prompt colors

These variables control the colors used when you are not inside a Git repository:

```
C_USER_PS1_COLOR='\[\e[0;32m\]'
C_ROOT_PS1_COLOR='\[\e[0;31m\]'
C_PATH_COLOR='\[\e[38;5;178m\]'
C_RESET='\[\e[0m\]'
```

#### Outside Git repository prompt structure

These variables define the prompt layout outside Git repositories:

```
PS1_OUTSIDE_USER="${C_USER_PS1_COLOR}\u@\h${C_RESET} ${C_PATH_COLOR}\w${C_RESET} \$ "
PS1_OUTSIDE_ROOT="${C_ROOT_PS1_COLOR}\u@\h${C_RESET} ${C_PATH_COLOR}\w${C_RESET} # "
```

You can safely modify:
- Colors  
- Username and hostname display  
- Path formatting  
- Prompt character  

The Git prompt behavior will continue to work normally.

---

### Troubleshooting

**Symbols not showing correctly:**
Make sure your terminal uses *JetBrainsMono Nerd Font Mono*.
Restart your terminal after installing fonts.
Log out and back in after installing fonts.

**Prompt not loading:**
Verify these lines exist and are correct in `~/.bashrc`:
```
# Git Prompt Start
if [ -f "$HOME/.bash-git-prompt/bash-git-prompt" ]; then
    export GIT_PROMPT_THEME=1
    source "$HOME/.bash-git-prompt/bash-git-prompt"
fi
# Git Prompt Stop
```

---

### FAQ

**Q:** Does this replace my default prompt entirely?  
**A:** While loaded, the script manages PS1 so it can switch automatically between Git and non-Git directories. Outside repositories a simplified prompt is shown; inside repositories the Git-aware prompt is shown.

**Q:** Can I create my own theme?  
**A:** Absolutely. Each theme is defined in the script under `set_git_prompt_theme_icons()`.
You can modify or extend it, then set your new theme using `export GIT_PROMPT_THEME=<number>`.

**Q:** Does it slow down Git-heavy directories?  
**A:** Negligibly. The script uses optimized Git calls and caches status checks for performance.

---

### More Information

More guides and documentation can be found on [wiki.x-files.dk](https://wiki.x-files.dk)

---

### License
Licensed under the [MIT License](./LICENSE).
