dotfiles

name	dotfiles
description	Reference for repository dotfiles, including their purposes, standard configurations, and usage guidelines. You MUST load this skill when configuring, troubleshooting, or understanding repository dotfiles.
license	MIT

dotfiles

WHEN TO USE

• Identifying the correct dotfile to modify for a specific configuration change (e.g., formatting, linting, git behavior).
• Troubleshooting CI/CD, linting, formatting, or environment configuration issues.
• Setting up a new repository with standard organizational configuration files.
• Understanding the purpose of existing hidden configuration files in the root directory.

WHEN NOT TO USE

• Modifying application-specific source code or core business logic.
• Configuring cloud infrastructure outside the repository itself (e.g., Terraform, AWS).
• Modifying standard documentation files (README.md, CONTRIBUTING.md) that are not hidden dotfiles.

Step-by-Step Workflows

Configuring a Dotfile

1. Identify the Scope: Determine what needs configuring (e.g., editor settings, git attributes, linting rules, dependency management).
2. Locate the Dotfile: Find the appropriate dotfile in the repository root or .github/ directory.
3. Analyze Existing Configuration: Read the file to understand current rules, overrides, and syntax.
4. Apply Changes: Modify the configuration following the specific tool's exact documentation and syntax.
5. Verify Changes: Run the associated tool (linter, formatter, or git command) to ensure changes are valid and have the intended effect.

Dotfile Reference

Git-Specific Dotfiles

• .git/: The hidden directory containing the repository's Git metadata, objects, and configuration. CRITICAL: Never modify files within this directory manually.
• .gitattributes: Defines Git attributes per path, controlling line ending normalization, merge strategies, text/binary classification, and diff output.
• .gitconfig: The global Git configuration file (typically in $HOME), containing user identity, global aliases, and default behaviors.
• .gitignore: Specifies intentionally untracked files to ignore (e.g., build artifacts, temporary files, secrets) preventing them from being committed to the Git repository.
• .gitmodules: Configures Git submodules, mapping their paths to the remote repository URLs.

Workspace Dotfiles

• .astro/config.yaml: Configuration file for the Astro web framework, defining build options, integrations, and project settings.
• .claude/: Directory containing workspace-specific Claude configuration, such as settings.json for hooks, tool permissions, and model or other workspace settings.
• .cursor/: Directory for Cursor-specific workspace configurations, including project-specific rules, indexing settings, and AI behavior overrides.
• .cursorrules: Defines custom instructions and behavioral rules for the Cursor AI editor, ensuring consistent AI assistance across the project.
• .devcontainer/: Directory for containerized development environments, containing devcontainer.json (configuration), requirements.txt (Python dependencies), and apt-packages.txt (system packages).
• .dockerignore: Specifies files and directories to exclude from the Docker build context, reducing image size and preventing sensitive files from being included.
• .editorconfig: Defines consistent coding styles (indentation, line endings, character set) for multiple developers working on the same project across various IDEs.
• .env.example / .env.sample / .env.dist: Provides a template of required environment variables without including actual secret values.
• .fdignore: Specifies files and directories to ignore for the fd search tool, often mirroring .gitignore but used for faster file finding.
• .gemini/: Directory containing configuration for Google Gemini, such as settings.json which typically points it to use AGENTS.md for context.
• .geminiignore: Specifies files and directories that Google Gemini tooling should ignore when indexing, reading, or using repository context, helping exclude generated files, secrets, and other irrelevant content.
• .github/CODEOWNERS: Defines individuals or teams responsible for specific code paths, automatically assigning them as PR reviewers.
• : Structured templates for bug reports and feature requests to ensure consistent issue reporting.

Linux-specific & User Home ($HOME) Dotfiles

• .bash_history: Stores the command history for the Bash shell.
• .bash_profile / .profile: Initialization scripts for login shells; .bash_profile is Bash-specific, while .profile is a more general fallback.
• .bashrc: The primary initialization script for non-login Bash shells, used for aliases, environment variables, and prompt settings.
• .cache/: Directory for user-specific non-essential data (XDG_CACHE_HOME), such as downloaded files or temporary application state.
• .config/: Directory for user-specific configuration files (XDG_CONFIG_HOME), following the XDG Base Directory Specification.
• .ctags: Configuration for Ctags, used to define how source code symbols are indexed for navigation.
• .curlrc: Default configuration for the curl command-line tool, used to specify common flags or proxy settings.
• .drush/: Configuration directory for Drush (Drupal Shell), containing aliases and command-specific settings.
• .eget.toml: Eget configuration file. Typically stored at ~/.eget.toml; Eget also supports the XDG fallback path ~/.config/eget/eget.toml, a config file alongside the Eget binary, or a path set via EGET_CONFIG. It defines global defaults and per-repository settings such as target, system, asset_filters, upgrade_only, and checksum verification behavior.
• .gdbinit: Initialization script for the GDB debugger, used to define custom commands or UI settings.
• .gnupg/: Directory for GnuPG (GNU Privacy Guard) configuration, keys, and trust database.
• .hyper.js: Configuration file for the Hyper terminal emulator.
• .inputrc: Configuration for the Readline library, used by shells (Bash) and other CLI tools for line editing and history.
• .lesshst: Stores the search and command history for the pager.

AI Agent & HOME-Oriented Dotfiles

• ~/.claude/: Home-level Claude configuration directory; Grok also reads compatible Claude marketplaces, plugins, skills, MCPs, and instruction files from here for cross-tool compatibility.
• ~/.claude/plugins/known_marketplaces.json: Claude-compatible marketplace source file that Grok can discover for additional marketplace entries.
• ~/.copilot/: Home-level GitHub Copilot user configuration directory for user-scoped agent preferences and tooling settings.
• ~/.grok/: Home-level Grok (X.ai) configuration directory; Grok discovers user-global skills from ~/.grok/skills/, plugins from ~/.grok/plugins/, and marketplace sources from ~/.grok/config.toml.
• ~/.grok/config.toml: User-global Grok configuration, including [[marketplace.sources]] entries for skill and plugin marketplace discovery.
• ~/.grok/plugins/: User-global Grok plugins available across all repositories.
• ~/.grok/skills/: User-global Grok skills available across all repositories.

Best Practices

• Keep it Minimal: Only add necessary rules; rely on community standard defaults where possible.
• Document Non-Standard Rules: If a configuration deviates from standard conventions, add an inline comment explaining why.
• Merge, Don't Replace: When updating existing configuration files, merge organizational standards into the existing content rather than replacing the file entirely. Preserve project-specific customizations whenever possible.
• Lexicographical Order: Maintain hooks in .pre-commit-config.yaml and other list-based configurations in alphabetical order.
• Standard Formatting: Use 4-space indentation for most files, but 2-space for YAML and JSON in .editorconfig.
• Test Hooks Locally: Always test .pre-commit-config.yaml changes locally by running pre-commit run --all-files before pushing.
• Use .env.example: Never commit actual .env files. Maintain an up-to-date .env.example for developers to copy.

Common Snippets

Search for dotfiles repositories

gh search repos "dotfiles" --limit 20

Common Pitfalls

• Overlapping Rules: Configuring conflicting rules in .editorconfig and language-specific linters (e.g., Prettier/ESLint). Ensure linter configs take precedence or align exactly with .editorconfig.
• Ignoring Generated Files: Forgetting to add build output directories (like node_modules/, dist/, .venv/) to .gitignore, leading to massive, unwanted commits.
• Incorrect Line Endings: Not enforcing * text=auto eol=lf in .gitattributes, causing cross-platform line ending issues (CRLF vs LF) and noisy git diffs.
• Hardcoding Secrets: Accidentally committing secrets because .env wasn't added to .gitignore before creating the file.

Related Skills

• agent-md: You MUST load this skill when working with AGENTS.md or other agent-specific configuration files.
• code-tour: You MUST load this skill when creating or updating .tours/ files.
• devcontainer: You MUST load this skill when managing .devcontainer/ configurations.
• dot-github: You MUST load this skill when standardizing or updating the .github/ directory structure.
• editorconfig: You MUST load this skill when creating or updating an .editorconfig file.
• gitattributes: You MUST load this skill when configuring Git behaviors via .gitattributes.
• gh-search: You MUST load this skill when searching for repositories or code examples using the GitHub CLI.
• github-actions: You MUST load this skill when troubleshooting or configuring GitHub Actions workflows.
• pre-commit: You MUST load this skill when managing pre-commit hooks.
• yaml: You MUST load this skill when updating YAML configuration dotfiles.