Add base configuration

- Follow XDG standard: ~/.config and ~/.local folders
- Set environment variables and define aliases within ~/.config/shell
- Add installation script for easy setup and maintenance
  (i.e., `dotfiles-install` and `dotfiles-update`)
- Add README.md with info on the installation and general notes
This commit is contained in:
Alexander Hess 2026-06-11 18:28:00 +02:00
commit a89c4955c5
Signed by: alexander
GPG key ID: B46EDB4DFC26805D
13 changed files with 583 additions and 0 deletions

14
.bashrc Normal file
View file

@ -0,0 +1,14 @@
#!/bin/bash
# `bash`-specific configurations
# Prevent running this file twice, as a non-login `bash` enters here,
# sources ~/.profile, and ~/.profile sources this file again
[ -n "$BASHRC_LOADED" ] && return
BASHRC_LOADED=1
# Load configuration files common to all kinds of shells,
# if not already done by a `bash` login shell
[ -z "$PROFILE_LOADED" ] && [ -f "$HOME/.profile" ] && . "$HOME/.profile"

14
.config/shell/README.md Normal file
View file

@ -0,0 +1,14 @@
# Shell-related Configurations
This folder contains files that are sourced by `bash` and `zsh`.
They are not executable.
The `#!/bin/sh` line documents the dialect for readers and editors;
it has no effect, since the files are sourced and never run directly.
[`aliases`](./aliases),
[`env`](./env),
[`logout`](./logout), and
[`welcome`](./welcome)
depend on helper functions defined in [`~/.profile`](../../.profile),
so they cannot work standalone.

55
.config/shell/aliases Normal file
View file

@ -0,0 +1,55 @@
#!/bin/sh
# Aliases used in all kinds of shells
# Manage the bare `git` repository in ~/ holding the dotfiles
alias dotfiles='git --git-dir=$DOTFILES_DIR --work-tree=$HOME'
alias path='echo $PATH | tr ":" "\n"'
# Easier `cd` movements
alias ..='cd ..'
alias ...='cd ../..'
alias ....='cd ../../..'
alias .....='cd ../../../..'
# Use human-readable sizes
alias df='df --human-readable'
alias du='du --human-readable'
alias free='free --human'
# Make the terminal more colorful
alias diff='diff --color=auto'
alias grep='grep --color=auto --exclude-dir=.git'
alias ip='ip -color=auto'
if _command_exists dircolors; then
# Compute `$LS_COLORS` only once because this file is also sourced
# by every non-interactive `bash` via `$BASH_ENV` (e.g., ":!cmd" in `vi`)
if [ -z "${LS_COLORS:-}" ]; then
if [ -r "$XDG_CONFIG_HOME/dircolors" ]; then
eval "$(dircolors -b "$XDG_CONFIG_HOME/dircolors")"
else
eval "$(dircolors -b)"
fi
fi
alias ls='ls --color=auto'
fi
# Add common `ls` utilities
alias l='ls --classify --format=vertical'
alias la='ls --classify --format=vertical --almost-all'
alias lal='ls --classify --format=long --almost-all'
alias ll='ls --classify --format=long'
alias lla='lal'

52
.config/shell/env Normal file
View file

@ -0,0 +1,52 @@
#!/bin/sh
# Environment variables for all kinds of shells
# Standard XDG base directories
# See: https://wiki.archlinux.org/title/XDG_Base_Directory
export XDG_CACHE_HOME="$HOME/.cache"
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_STATE_HOME="$HOME/.local/state"
# Make up a XDG directory for binaries (that does not exist in the standard)
export XDG_BIN_HOME="$HOME/.local/bin"
# Convenient names for various places in the system,
# shown here not only to be used but also document things
export DOTFILES_DIR="$XDG_DATA_HOME/dotfiles"
export DOTFILES_HTTPS="https://code.webartifex.de/alexander/dotfiles"
export DOTFILES_SSH="git@git.webartifex.de:alexander/dotfiles.git"
# Generic shell configs
# Fall back to a widely known terminal type
# if this host lacks the terminfo entry for `$TERM`
# (e.g., `alacritty` over `ssh` on a fresh server)
if _command_exists infocmp && ! infocmp "$TERM" >/dev/null 2>&1; then
export TERM=xterm-256color
fi
[ -t 0 ] && export GPG_TTY=$(tty)
export EDITOR=nano
export PAGER=less
export LESS="--chop-long-lines --ignore-case --LONG-PROMPT --no-init --quit-if-one-screen --RAW-CONTROL-CHARS --status-column"
[ -f "$XDG_CONFIG_HOME/shell/locale" ] && . "$XDG_CONFIG_HOME/shell/locale"
# Move common tools' config and cache files into XDG directories
export LESSHISTFILE="$XDG_STATE_HOME/less/history"

24
.config/shell/locale Normal file
View file

@ -0,0 +1,24 @@
#!/bin/sh
# Locale settings for headless machines
# Drop what a client may forward over `ssh`,
# because `AcceptEnv LANG LC_*` may be set in /etc/ssh/sshd_config
unset \
LC_ALL \
LC_ADDRESS \
LC_COLLATE \
LC_CTYPE LC_IDENTIFICATION \
LC_MEASUREMENT \
LC_MESSAGES \
LC_MONETARY \
LC_NAME \
LC_NUMERIC \
LC_PAPER \
LC_TELEPHONE \
LC_TIME
# Set every LC_* category implicitly with the `$LANG` fallback
export LANG=C.UTF-8

3
.local/bin/README.md Normal file
View file

@ -0,0 +1,3 @@
# User-local Executables
This folder contains executable files that are on the `$PATH`.

146
.local/bin/dotfiles-install Executable file
View file

@ -0,0 +1,146 @@
#!/bin/sh
# Installation script to make the dotfiles available in ~/
#
# `git` is the only dependency for this script to run (See: https://git-scm.com)
#
# See: https://code.webartifex.de/alexander/dotfiles#installation
set -eu
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
# Each branch's first commit sets the default to its own name
# => Overridable via the environment (e.g., done by `dotfiles-update`)
DOTFILES_BRANCH="${DOTFILES_BRANCH:-main}"
DOTFILES_DIR="${DOTFILES_DIR:-$XDG_DATA_HOME/dotfiles}"
DOTFILES_HTTPS="${DOTFILES_HTTPS:-https://code.webartifex.de/alexander/dotfiles}"
BACKUPS_DIR="$XDG_STATE_HOME/dotfiles-backups"
BACKUP_DIR="$BACKUPS_DIR/$(date +%Y%m%d-%H%M%S)"
_force=0
if [ "$#" -gt 1 ]; then
echo "Usage: $(basename "$0") [--force]" >&2
exit 1
fi
case "${1:-}" in
"") ;;
--force) _force=1 ;;
*)
echo "Usage: $(basename "$0") [--force]" >&2
exit 1
;;
esac
if [ -d "$DOTFILES_DIR" ]; then
if [ "$_force" -ne 1 ]; then
echo ""
echo "The dotfiles are already installed at: $DOTFILES_DIR"
echo ""
echo "Options:"
echo " - Run the installation again with '--force'"
echo " - Update with 'dotfiles pull' and continue using them"
echo ""
exit 0
fi
echo "Backing up the existing repository to: $BACKUP_DIR"
mkdir -p "$BACKUP_DIR"
mv "$DOTFILES_DIR" "$BACKUP_DIR/dotfiles"
fi
git clone --bare "$DOTFILES_HTTPS" "$DOTFILES_DIR"
_git() {
git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" "$@"
}
if ! _git show-ref --verify --quiet "refs/heads/$DOTFILES_BRANCH"; then
echo "" >&2
echo "Internal error: branch '$DOTFILES_BRANCH' missing in the repository" >&2
echo "" >&2
echo "Available branches:" >&2
_git branch --format=' %(refname:short)' >&2
echo "" >&2
exit 1
fi
_git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
_git fetch origin
# Do not checkout project documentation intended for web GUIs
#
# Note: The patterns match at every depth, like in a .gitignore,
# which excludes the per-folder README.md files as well
_git config core.sparseCheckout true
{
echo "/*"
echo "!LICENSE.txt"
echo "!README.md"
} > "$DOTFILES_DIR/info/sparse-checkout"
# Back up files in the user's $HOME folder if a checkout is about to overwrite them
#
# Note: This may also back up local-only files marked sparse in the repo,
# which is not considered a big problem because it's very unlikely
_conflicts=$(_git ls-tree -r --name-only "$DOTFILES_BRANCH" | while IFS= read -r f; do
if [ -e "$HOME/$f" ] || [ -L "$HOME/$f" ]; then echo "$f"; fi
done)
if [ -n "$_conflicts" ]; then
echo "Backing up pre-existing files to: $BACKUP_DIR"
echo "$_conflicts" | while IFS= read -r f; do
mkdir -p "$BACKUP_DIR/$(dirname "$f")"
cp -a "$HOME/$f" "$BACKUP_DIR/$f"
done
fi
# Put the dotfiles in the user's $HOME folder
_git checkout --force "$DOTFILES_BRANCH"
# Do not show files not tracked in the dotfiles repository because there are simply too many
_git config --local status.showUntrackedFiles no
# Keep only the most recent backups
_keep=10
if [ -d "$BACKUPS_DIR" ]; then
# `head -n -N` is a GNU extension; fine on Debian, fails on, e.g., BSD/BusyBox
find "$BACKUPS_DIR" -mindepth 1 -maxdepth 1 -type d | sort | head -n -"$_keep" \
| while IFS= read -r _old; do
rm -f -r "$_old"
done
fi
echo ""
echo "The dotfiles were installed successfully (branch: $DOTFILES_BRANCH)"
echo ""
echo "Reload your shell to use them:"
echo " exec \$SHELL -l"
echo ""

116
.local/bin/dotfiles-update Executable file
View file

@ -0,0 +1,116 @@
#!/bin/sh
# Replace the local `dotfiles` repository with a fresh install
# by re-running the latest `dotfiles-install` taken from the `origin`
#
# Refuses to run if there are uncommitted or unpushed changes,
# unless called with `--force`
set -eu
XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
DOTFILES_DIR="${DOTFILES_DIR:-$XDG_DATA_HOME/dotfiles}"
_force=0
if [ "$#" -gt 1 ]; then
echo "Usage: $(basename "$0") [--force]" >&2
exit 1
fi
case "${1:-}" in
"") ;;
--force) _force=1 ;;
*)
echo "Usage: $(basename "$0") [--force]" >&2
exit 1
;;
esac
if [ ! -d "$DOTFILES_DIR" ]; then
echo "" >&2
echo "The dotfiles are not installed at: $DOTFILES_DIR" >&2
echo "" >&2
echo "=> See instructions at https://code.webartifex.de/alexander/dotfiles#installation" >&2
echo "" >&2
exit 1
fi
_git() {
git --git-dir="$DOTFILES_DIR" --work-tree="$HOME" "$@"
}
# Keep the machine on its current branch (e.g., "desktop")
branch=$(_git symbolic-ref --short HEAD) || {
echo "" >&2
echo "Detached HEAD => Re-run after 'dotfiles checkout <branch>'" >&2
echo "" >&2
exit 1
}
if [ "$_force" -ne 1 ]; then
if [ -n "$(_git status --porcelain)" ]; then
echo "" >&2
echo "There are uncommitted changes!" >&2
echo "" >&2
_git --no-pager diff HEAD --stat >&2
echo "" >&2
echo "=> Commit and push them, or re-run with '--force'" >&2
echo "" >&2
exit 1
fi
if _git rev-parse --verify --quiet "origin/$branch" >/dev/null \
&& [ -n "$(_git log --oneline "origin/$branch..$branch")" ]; then
echo "" >&2
echo "There are unpushed commits!" >&2
echo "" >&2
_git --no-pager log --oneline "origin/$branch..$branch" >&2
echo "" >&2
echo "=> Push them, or re-run with '--force'" >&2
echo "" >&2
exit 1
fi
fi
# Take the latest installer out of the local repository,
# after fetching from the `origin`
_git fetch --prune origin
if ! _git rev-parse --verify --quiet "origin/$branch" >/dev/null; then
echo "" >&2
echo "Branch '$branch' does not exist on origin!" >&2
echo "" >&2
echo "=> Push it first, or 'dotfiles checkout' one that does" >&2
echo "" >&2
exit 1
fi
installer_path=$(mktemp)
trap 'rm -f "$installer_path"' EXIT
_git show "origin/$branch:.local/bin/dotfiles-install" > "$installer_path"
DOTFILES_BRANCH="$branch" sh "$installer_path" --force

8
.local/state/README.md Normal file
View file

@ -0,0 +1,8 @@
# State Placeholders
This folder contains empty `.gitkeep`-tracked placeholders
for the history and state files
set in [`~/.config/shell/env`](../../.config/shell/env)
and also other configuration files.
The state files themselves are untracked.

View file

83
.profile Normal file
View file

@ -0,0 +1,83 @@
#!/bin/sh
# Main setup file executed for all kinds of shells
# Prevent loading ~/.profile twice in `bash`
export PROFILE_LOADED=1
# Basic utilities
_command_exists() {
command -v "$1" 1>/dev/null 2>&1
}
_in_bash() {
[ -n "$BASH_VERSION" ]
}
_in_zsh() {
[ -n "$ZSH_VERSION" ]
}
_prepend_to_path () {
if [ -d "$1" ] ; then # Ignore non-existing directories
case :$PATH: in
*:"$1":*) ;; # Already in the `$PATH` => Do nothing
*) PATH=$1:$PATH ;; # Otherwise, prepend it
esac
fi
}
_remove_from_path () {
_rest=$PATH # Not yet processed `$PATH`s
_new= # `$PATH`s collected so far
while [ -n "$_rest" ]; do # Rebuild the `$PATH` entry by entry
_dir=${_rest%%:*} # First remaining entry
case $_rest in
*:*) _rest=${_rest#*:} ;; # Drop that entry and its colon
*) _rest= ;; # Last entry read => Stop
esac
[ "$_dir" = "$1" ] && continue # Skip on an exact match
_new=${_new:+$_new:}$_dir # Append, avoiding a leading colon
done
PATH=$_new
unset _dir _new _rest
}
_remove_from_path "/usr/games"
_remove_from_path "/usr/local/games"
_prepend_to_path "$HOME/.local/bin"
# Needs ~/.local/bin on the `$PATH` already
# because it checks existence of some binaries
[ -f "$HOME/.config/shell/env" ] && . "$HOME/.config/shell/env"
[ -f "$HOME/.config/shell/aliases" ] && . "$HOME/.config/shell/aliases"
# Source ~/.profile_local, which holds machine-specific ENV variables
[ -f "$HOME/.profile_local" ] && . "$HOME/.profile_local"
# Load `bash`-specific configurations
if [ -n "$BASH_VERSION" ] && [ -f "$HOME/.bashrc" ]; then
. "$HOME/.bashrc"
fi
# Ensure ~/.profile is loaded each time `bash` starts
unset PROFILE_LOADED

7
.zshrc Normal file
View file

@ -0,0 +1,7 @@
#!/bin/zsh
# `zsh`-specific configurations
# Load configuration files common to all kinds of shells
[ -f "$HOME/.profile" ] && . "$HOME/.profile"

61
README.md Normal file
View file

@ -0,0 +1,61 @@
# Dotfiles
This repository contains useful (config) files.
There are two branches:
- [*main*](https://code.webartifex.de/alexander/dotfiles/src/branch/main) (~ "headless")
- [*desktop*](https://code.webartifex.de/alexander/dotfiles/src/branch/desktop) (for GNOME 48+ on X11)
`main` contains dotfiles intended to be used on all kinds of machines
and can be thought of as a "minimal" or "server" version.
It targets [Debian](https://www.debian.org/) 13
but is kept working on older versions and other distributions as well.
`desktop` is (re-)based on top of `main`
and adds configurations for
[GNOME](https://www.gnome.org/) 48+
on [X11](https://www.x.org/)
and many applications,
be it end-user software or common development utilities.
## Installation
Simply run:
```sh
curl https://code.webartifex.de/alexander/dotfiles/raw/branch/main/.local/bin/dotfiles-install > dotfiles-install && sh ./dotfiles-install && rm ./dotfiles-install
```
or
```sh
wget https://code.webartifex.de/alexander/dotfiles/raw/branch/main/.local/bin/dotfiles-install -O dotfiles-install && sh ./dotfiles-install && rm ./dotfiles-install
```
This downloads a simple [installation script](.local/bin/dotfiles-install)
and then executes it.
The script's only dependency is [`git`](https://git-scm.com/).
So, it should not be too hard to get this going.
The repository is cloned as a bare repository into `~/.local/share/dotfiles`
and its files are checked out into `~/` directly.
Pre-existing files are backed up to `~/.local/state/dotfiles-backups` beforehand.
Afterwards, the files can be managed with the
[`dotfiles` alias](.config/shell/aliases),
for example, `dotfiles status` or `dotfiles pull`.
The above commands install the *main* variant.
To install the *desktop* variant,
switch to the [desktop](https://code.webartifex.de/alexander/dotfiles/src/branch/desktop) branch first.
Normally, I advise against executing shell scripts from the internet,
but this one is short enough to be read even by beginners.
So, convince yourself that it is not harmful!
## Shells
The config files in this repository are optimized for usage with
[GNU's Bourne again shell](https://man7.org/linux/man-pages/man1/bash.1.html),
or `bash` for short,
and the popular [zsh](https://www.zsh.org/).