mauvehed.com
mauvehed's dotfiles for personal and work environments
1# System Usage & OS-Specific Notes
2
3This document outlines system-level configurations, OS-specific notes, and common utilities relevant to this dotfiles setup across different operating systems.
4
5## Overview
6
7These dotfiles aim to provide a consistent experience across macOS, Linux (primarily Ubuntu), and Windows (via WSL). `chezmoi` plays a crucial role in managing OS-specific configurations by using templates and conditional logic based on the operating system.
8
9## General Principles
10
11* **`chezmoi` for OS Detection**: `chezmoi` templates often use variables like `.chezmoi.os` (e.g., "darwin", "linux", "windows") to apply OS-specific settings or install different packages.
12* **Homebrew/Linuxbrew**: Homebrew (on macOS) and Linuxbrew (on Linux) are heavily utilized for package management. See `Brewfile` or `chezmoi` scripts for lists of managed packages.
13* **Common Utilities**: Many command-line utilities are installed for enhanced productivity. Some common examples that might be included (and configured by these dotfiles) are:
14 * `exa` or `lsd` (modern `ls` replacements)
15 * `bat` (a `cat` clone with syntax highlighting)
16 * `fd` (a simple, fast, and user-friendly alternative to `find`)
17 * `ripgrep` (`rg`) (a line-oriented search tool that recursively searches your current directory for a regex pattern)
18 * `fzf` (a command-line fuzzy finder)
19 * `zoxide` (a smarter `cd` command)
20 * `htop` or `btop` (interactive process viewers)
21
22## macOS Specifics
23
24* **Package Manager**: [Homebrew](https://brew.sh/) is the primary package manager.
25* **Shell**: Zsh, configured via `oh-my-zsh` and `oh-my-posh` (see `docs/terminal-usage.md`).
26* **Finder Tweaks**: Your `chezmoi` setup might include scripts to apply common Finder settings (e.g., show hidden files, show path bar).
27 * Example commands (often found in `run_once_` scripts):
28 ```sh
29 # Show hidden files
30 # defaults write com.apple.finder AppleShowAllFiles -bool true
31 # Show path bar
32 # defaults write com.apple.finder ShowPathbar -bool true
33 # Restart Finder to apply changes
34 # killall Finder
35 ```
36* **Keyboard Shortcuts/Remapping**: Tools like Karabiner-Elements might be used for advanced keyboard customization (if included in your setup).
37* **Spotlight**: Useful for launching applications and finding files (`Cmd+Space`).
38* **System Updates**: `sudo softwareupdate -i -a`
39
40## Linux (Ubuntu Focus)
41
42* **Package Manager**: `apt` is the system package manager. [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) might also be used for user-space packages.
43* **Shell**: Zsh, configured via `oh-my-zsh` and `oh-my-posh` (see `docs/terminal-usage.md`).
44* **System Updates**:
45 ```sh
46 sudo apt update && sudo apt upgrade -y
47 sudo apt autoremove -y # To remove unused packages
48 ```
49* **Firewall**: `ufw` (Uncomplicated Firewall) is commonly used.
50 ```sh
51 # sudo ufw status
52 # sudo ufw enable
53 # sudo ufw allow ssh
54 ```
55
56## Windows (via WSL - Windows Subsystem for Linux)
57
58* **WSL Version**: It's recommended to use WSL 2 for better performance and system call compatibility.
59* **Distribution**: Typically Ubuntu is used within WSL, so many Linux notes apply.
60* **Accessing Windows Files**: Windows drives are typically mounted under `/mnt/` (e.g., `/mnt/c`).
61* **Windows Terminal**: Recommended for a better WSL experience.
62* **Interoperability**: You can run Windows executables from WSL and Linux executables from Windows (PowerShell/CMD).
63* **Docker Desktop with WSL Backend**: Often used for Docker development on Windows.
64
65## GitHub Codespaces
66
67GitHub Codespaces typically run a Linux environment (often Ubuntu-based).
68* **Dotfiles Integration**: Your dotfiles can be automatically installed into Codespaces if configured in your GitHub settings.
69* **`devcontainer.json`**: Projects can define specific configurations for Codespaces using a `devcontainer.json` file, which can include features, extensions, and post-create commands.
70* The environment is largely Linux-based, so Linux configurations from your dotfiles will apply.
71
72## Resources
73
74* **macOS User Guide**: [https://support.apple.com/guide/mac-help/welcome/mac](https://support.apple.com/guide/mac-help/welcome/mac)
75* **Ubuntu Server Guide / Desktop Guide**: [https://ubuntu.com/server/docs](https://ubuntu.com/server/docs), [https://ubuntu.com/desktop/docs](https://ubuntu.com/desktop/docs)
76* **Windows Subsystem for Linux (WSL) Documentation**: [https://docs.microsoft.com/en-us/windows/wsl/](https://docs.microsoft.com/en-us/windows/wsl/)
77* **Chezmoi Documentation (OS specific logic)**: [https://www.chezmoi.io/user-guide/templating/#variables](https://www.chezmoi.io/user-guide/templating/#variables)
78* **Homebrew**: [https://brew.sh/](https://brew.sh/)
79* **Linuxbrew**: [https://docs.brew.sh/Homebrew-on-Linux](https://docs.brew.sh/Homebrew-on-Linux)
80
81This document provides a high-level overview. Specific configurations and scripts are managed by `chezmoi` and can be found within the repository.