alacrittyfiles

Personal Alacritty configuration with the Catppuccin Mocha theme

---

Table of Contents

• Overview
• Important Notice
• Prerequisites
• Installation
• Active Theme
• Submodule Maintenance
• Updates
• Troubleshooting
• Contributing

---

Overview

This repository contains a personal Alacritty configuration. It mirrors the official Alacritty theme repository on GitHub via a Git submodule — so it's important to keep the themes submodule up to date, as described below.

The configuration applies the Catppuccin Mocha theme with a reduced 95% opacity.

---

Important Notice

Make sure Alacritty is installed and working before proceeding. If you already have custom Alacritty configuration on your machine, it will likely conflict with this repository's files. In that case, back up and remove your previous configuration before continuing.

# Back up your current configuration
cp -r ~/.config/alacritty ~/.config/alacritty.bak

# Remove the previous configuration
rm -rf ~/.config/alacritty

---

Prerequisites

• Alacritty installed and working
• Git installed and configured (version 2.13 or later, for full --recurse-submodules support)

---

Installation

⚠️ The safest way to install is to clone with submodules already included, using --recurse-submodules. This avoids the issue described in Troubleshooting, where the themes/ directory is declared in .gitmodules but not recognized by Git.

1. Close Alacritty and clone the repository with submodules included:

From the private Forgejo instance:

git clone --recurse-submodules https://forge.itamarcampos.com.br/itamcampos/alacrittyfiles.git ~/.config/alacritty

From GitHub:

git clone --recurse-submodules https://github.com/itamcampos/alacrittyfiles.git ~/.config/alacritty

From Codeberg:

git clone --recurse-submodules https://codeberg.org/itamcampos/alacrittyfiles.git ~/.config/alacritty

2. Enter the cloned directory:

cd ~/.config/alacritty

3. Verify that the submodule was downloaded correctly:

git submodule status

The expected output is a line starting with a space (or nothing, depending on your Git version) followed by a commit hash and the themes path, e.g.:

 a1b2c3d4e5f6... themes (heads/master)

If the themes/ folder is empty or the command returns no output at all, follow the Troubleshooting section before continuing.

4. Confirm the theme files actually exist:

ls themes/themes/*.toml | head -n 5

If this list comes back empty, the submodule wasn't downloaded — go back to step 3.

5. Reopen Alacritty and check that the changes were applied.

Installing without --recurse-submodules

If you already cloned the repository without that flag, run the following commands inside ~/.config/alacritty to fetch the submodule:

git submodule init
git submodule update
git submodule status   # should show the "themes" hash, not an empty line

---

Active Theme

The configured color scheme is Catppuccin Mocha, available in the official Alacritty theme repository. In addition to the theme, the configuration sets the terminal window opacity to 95%.

Setting	Value
Theme	catppuccin_mocha.toml
Opacity	0.95

---

Submodule Maintenance

The themes/ directory is a Git submodule pointing to the official Alacritty theme repository. Use the commands below to keep it up to date.

Initialize the submodule (needed only once, after a clone without --recurse-submodules):

git submodule init

Update the submodule to the revision recorded in the main repository:

git submodule update

Update the submodule to the latest commit from the remote theme repository:

git submodule update --remote themes

This command only works if themes is already registered as a submodule in Git's index. If it fails with error: pathspec 'themes' did not match any file(s) known to git, see Troubleshooting.

Check the current submodule state (always run this after any of the operations above):

git submodule status

Clone the repository with submodules already initialized:

git clone --recurse-submodules https://forge.itamarcampos.com.br/itamcampos/alacrittyfiles.git ~/.config/alacritty

---

Updates

To update the main configuration, run:

cd ~/.config/alacritty && git pull

To update the submodule themes:

git submodule update --remote themes
git submodule status   # confirm the hash changed / is correct

---

Troubleshooting

git submodule update --remote themes returns error: pathspec 'themes' did not match any file(s) known to git

Cause: .gitmodules declares the themes submodule, but the repository doesn't actually have the gitlink (a special mode-160000 entry) registered in the commit's index. This happens when the submodule was removed, was never added with git submodule add, or the history was rewritten (squash/rebase) and lost that reference.

Diagnosis:

# 1. Confirm .gitmodules exists and declares "themes"
cat .gitmodules

# 2. Confirm Git does NOT recognize "themes" as a submodule
git submodule status
# empty output = problem confirmed

# 3. Confirm there's no gitlink for "themes" in the current commit's tree
git ls-tree HEAD -- themes
# empty output = confirms "themes" isn't registered as a submodule

Fix:

# Remove any leftover folder (if it exists)
rm -rf themes

# Add the submodule properly, creating the gitlink in the index
git submodule add https://github.com/alacritty/alacritty-theme themes

# Verify it now shows up correctly
git submodule status

# If this is the shared remote repository (not just your local clone),
# commit the fix so future clones don't hit the same issue
git commit -m "fix: re-register themes submodule"
git push

themes/ is empty after cloning

You probably cloned without --recurse-submodules. Run:

git submodule init
git submodule update

Authentication/timeout error while fetching the submodule

The submodule points to https://github.com/alacritty/alacritty-theme. Check connectivity to GitHub separately from Forgejo/Codeberg:

git ls-remote https://github.com/alacritty/alacritty-theme

If this command fails, the issue is network/proxy-related, not the configuration repository itself.

git submodule status shows a - before the hash

A - prefix means the submodule is registered but not initialized. Just run:

git submodule update --init

git submodule status shows a + before the hash

A + prefix means the commit currently checked out in themes/ differs from the commit recorded in the main repository (usually after a git submodule update --remote). This is expected until you commit the update:

git add themes
git commit -m "chore: update themes submodule"

---

Contributing

Suggestions are welcome. Open an issue or submit a pull request.

---

_{Made by itamcampos}