.gitconfig

# Author: James Cherti
# URL: https://github.com/jamescherti/jc-dotfiles
#
# Description:
# ------------
# Git configuration (.gitconfig).
# Documentation: https://git-scm.com/docs/git-config
#
# License:
# --------
#
# Distributed under terms of the MIT license.
#
# Copyright (C) 2005-2025 James Cherti
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the “Software”), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
#

[tag]
# This setting forces all annotated tags to be GPG-signed when using
# 'git tag -a'.
forceSignAnnotated = true

[pack]
# Configures Git to auto-detect the number of CPUs and set the number of threads
# accordingly.
threads = 0

# Allocate up to 5GB as the amount of memory consumed by each thread in
# git-pack-objects for pack window memory when no limit is specified on the
# command line. This enhances Git’s efficiency for large repositories.
windowMemory = 5g

# The packSizeLimit configuration in Git determines the maximum size of a
# packfile that Git will generate. A packfile is a file that contains a
# collection of objects, such as commits, trees, and blobs, in a compressed
# format.
packSizeLimit = 2g

[gc]
# Automatically triggers garbage collection when the number of loose objects
# exceeds 8,000, optimizing repository storage and performance. When there are
# more than this number of loose objects in the repository, git gc --auto will
# pack them. Some porcelain commands use this to perform lightweight garbage
# collection periodically. The default value is 6,700.
auto = 8000

[core]
# -X: Keep the content visible after closing the pager
# -R: Ensures that color codes and other control characters in the output
#     (e.g., from 'git diff --color') are properly displayed in the pager.
pager = less -X -R

# Displays non-ASCII file names in their original form instead of quoted octal
# sequences.
quotepath = off

# Specifies a global ignore file for patterns to exclude across all
# repositories.
excludesfile = ~/.gitignore_global

# Use a global gitattributes file for applying attribute rules to all
# repositories
attributesfile = ~/.gitattributes_global

# Enables the untracked cache to speed up performance when checking for
# untracked files (default: false)
# This can be beneficial in large repositories where `git status` is run
# frequently, as it reduces the time spent scanning for untracked files.
untrackedCache = true

# trailing-space: look for spaces at the end of a line
# space-before-tab: look for spaces before tabs at beginning of line
# removed: indent-with-non-tab
whitespace = space-before-tab,trailing-space

# Prevent showing files whose names contain non-ASCII symbols as unversioned.
precomposeunicode = false

# Preloads the index into memory for improved performance when running Git
# commands like status and diff. Setting this to true will make Git load the
# index into memory early in the execution of commands. This can lead to
# performance improvements for operations that involve the index, especially in
# repositories with a large number of files.
preloadindex = true

[difftool]
# Disables the prompt asking whether to launch the diff tool for each file when
# using 'git difftool'
prompt = false

# This Git configuration enhances diffs for Emacs Lisp (elisp) files by defining
# a custom pattern to identify function boundaries. The xfuncname option uses a
# regular expression to match function definitions, allowing Git to detect
# functions more accurately. Without this, Git may show line-by-line changes
# without considering function structure.
#
# With this pattern, Git can display diffs at the function level, making them
# cleaner and more relevant. It highlights changes within the function, rather
# than showing the entire function as modified, which improves the clarity of
# code reviews and merges in Emacs Lisp code.
[diff "elisp"]
xfuncname = ^\\([^[:space:]]*def[^[:space:]]+[[:space:]]+([^()[:space:]]+)

[diff "cpp"]
xfuncname = "!^[ \\t]*[A-Za-z_][A-Za-z_0-9]*:[[:space:]]*($|/[/*])\n^((::[[:space:]]*)?[A-Za-z_][A-Za-z_0-9]*[[:space:]]*\\(.*)$\n^((#define[[:space:]]|DEFUN).*)$"

[diff "elisp"]
xfuncname = ^\\([^[:space:]]*def[^[:space:]]+[[:space:]]+([^()[:space:]]+)

[diff "m4"]
xfuncname = ^((m4_)?define|A._DEFUN(_ONCE)?)\\([^),]*

[diff "make"]
xfuncname = ^([$.[:alnum:]_].*:|[[:alnum:]_]+[[:space:]]*([*:+]?[:?]?|!?)=|define .*)

[diff "shell"]
xfuncname = ^([[:space:]]*[[:alpha:]_][[:alnum:]_]*[[:space:]]*\\(\\)|[[:alpha:]_][[:alnum:]_]*=)

[diff "texinfo"]
xfuncname = ^@node[[:space:]]+([^,[:space:]][^,]+)

[diff]
tool = vimdiff

# Diff algorithm for improved diff accuracy, especially in detecting moved code
# blocks.
#
# Patience diff is better at handling reordered text blocks by identifying
# unique lines first and using a longest-increasing subsequence algorithm for
# optimal alignment. It results in more intuitive and human-readable diffs.
# Compared to histogram-based algorithms, patience diff focuses on matching
# meaningful lines, avoiding superficial matches, which leads to more accurate
# content representation.
#
algorithm = histogram
# algorithm = patience

# Enable highlighting of moved lines in diffs. This helps identify blocks of
# code that have been moved within a file, making it easier to track code
# movement and understand refactoring changes.
# Values: no, default, plain, blocks, zebra, dimmed-zebra
# Details: `man git-diff`
colorMoved = plain

# Enable highlighting of moved whitespace in diffs. This setting makes it easier
# to spot changes where only whitespace (e.g., spaces or tabs) has been moved or
# modified, which is useful for identifying formatting changes without affecting
# the actual content of the code.
# Values: no, ignore-space-at-eol, ignore-space-change, ignore-all-space,
# allow-indentation-change
# Details: `man git-diff`
colorMovedWS = allow-indentation-change

# Show 5 lines of context around changes in diffs instead of the default 3
context = 5

# Git diff replaces a/ and b/ with context-sensitive, mnemonic prefixes based on
# the file's origin: i/ Index (staged content), w/ Working tree (your current
# files), c/ Current commit (HEAD), o/ Original (common ancestor in a merge), 1/
# 2/ 3/ Parent commits in combined merges
mnemonicPrefix = true

# Disables the default prefix (e.g., 'a/' and 'b/') in diff output, showing file
# names directly instead
noPrefix = true

# Configures Git to detect file copies in addition to renames during diff
# generation. This helps identify files that were copied, improving the accuracy
# of the diff output for changes involving file copying.
renames = copies

# Sets the maximum number of renames to detect in a diff. When there are more
# than this number of renames, Git will stop trying to detect renames to avoid
# performance degradation. The default is 1000, but increasing it can help in
# repos with many file renames.
renameLimit = 2400

[rerere]
# The "reuse recorded resolution" (rerere) feature, which helps Git
# automatically resolve merge conflicts by reusing previously recorded conflict
# resolutions. The setting enabled = 1 indicates that the rerere feature is
# enabled.
enabled = 1

# After a conflict is resolved manually, Git will automatically store the
# resolution in the rerere cache, making it available for future use.
autoUpdate = true

[commit]
# This includes the full commit diff in the text editor when composing the
# commit message, aiding in recalling the context and purpose of the changes.
verbose = true

# This option determines how the commit message should be cleaned up before
# committing. The available cleanup modes are as follows:
# - strip: Removes leading and trailing empty lines, trailing whitespace,
#   comments that start with #, and collapses consecutive empty lines in the
#   commit message.
# - whitespace: Similar to strip, but comments (lines starting with #) are
#   retained in the message.
# - verbatim: No changes are made to the commit message. It is preserved
#   exactly as it was supplied.
# - scissors: Similar to whitespace, but everything from (and including) the
#   line starting with a custom # marker (by default #
#   ------------------------ >8 ------------------------) will be truncated if
#   the message is being edited. This marker can be customized with
#   core.commentChar.
# - default: If the commit message is being edited, it behaves like strip. If
#   not being edited, it behaves like whitespace.
cleanup = strip

[color]
ui = auto

[rebase]
# Create a stash of any local changes before starting a rebase. After the rebase
# is complete, the stash is reapplied.
autoStash = true

# If commits are removed or missing during a rebase, issue an error rather than
# silently ignoring them.
missingCommitsCheck = error

# When you use interactive rebase (e.g., `git rebase -i`), this setting makes
# Git automatically recognize and handle commits that begin with "fixup!" or
# "squash!".
#
# - A commit with "squash!" means "combine this with another commit and keep
#   both messages".
# - A commit with "fixup!" means "combine this with another commit and discard
#   this message".
autoSquash = true

# when you have multiple stacked branches, it can become complex to handle the
# rebasing process manually for each branch, especially if you have many commits
# in each branch.
#
# Setting updateRefs to true simplifies this process. By enabling this option,
# whenever you perform a rebase operation on one branch, the references to the
# other dependent branches are automatically updated as well. This ensures that
# each branch in the stack remains properly aligned with the others, without
# requiring you to manually update or rebase each one individually.
updateRefs = true

[merge]
# This setting enforce fast-forward merges, preventing unnecessary merge commits
# and maintaining a linear commit history.
ff = only

# Uses the 'zdiff3' conflict style for merges, which includes additional context
# by showing the base, local, and remote versions of conflicting changes in a
# more readable format, making it easier to resolve complex conflicts.
conflictStyle = zdiff3

# Before executing a merge, automatically stash all uncommitted changes in the
# working directory and index. This ensures the merge proceeds without
# interference from local modifications. Once the merge completes, the stashed
# changes are reapplied, restoring the developer's original working state.
autoStash = true

# Display a brief summary describing what was merged. This includes information
# such as the merged branch names and the number of commits.
summary = true

# Display a diffstat after the merge completes, which summarizes the changes
# made, showing how many lines were added and removed in each file.
diffstat = true

# Include up to 60 commit messages from the merged branch in the merge commit
# message. This provides historical context and helps reviewers understand the
# scope of the merge.
log = 60

# Enables the inclusion of branch descriptions in merge commit messages,
# providing more context about the branches being merged.
branchdesc = true

[pull]
# This setting enforce fast-forward merges, preventing unnecessary merge commits
# and maintaining a linear commit history.
ff = only

[log]
# Display dates as YYYY-MM-DD
date = iso

# This configuration automatically pulls the current branch, which helps prevent
# "There is no tracking information for the current branch. Please specify which
# branch you want to merge with. See git-pull(1) for details. git pull <remote>
# <branch>"
default = current

[push]
# This configuration automatically pushes the current branch, which helps
# prevent the error: “fatal: The current branch BRANCH has no upstream branch.”
# When this setting is in place, Git will push the current branch to the remote,
# assuming the branch has an upstream set.
default = current

# This setting automatically sets up remote tracking for new branches,
# eliminating the need to manually run git branch --set-upstream-to after
# creating a new branch. It automates the process of linking local branches to
# their corresponding remote branches. This is particularly useful for users who
# frequently create new branches, as it reduces the need for repetitive
# configuration.
autoSetupRemote = true

# Push all annotated tags to the remote repository along with the branch
# updates. This ensures that tags created locally are also synchronized with the
# remote repository during a push operation.
followTags = true

[init]
# templatedir = ~/.git-templates
defaultBranch = main

[transfer]
# Verifies the integrity of all objects during data transfer operations like
# clone, helping detect corruption or tampering early.
fsckObjects = true

[fetch]
# Validates all objects during fetch to ensure no corrupted or malformed data is
# introduced into the local repository.
fsckObjects = true

# Automatically remove remote-tracking branches that no longer exist on the
# remote repository during a 'git fetch'. This helps keep the local repository
# clean by removing outdated references to remote branches that have been
# deleted.
prune = true

# Automatically delete remote tags in your local repository that have been #
# removed from the remote repository during a 'git fetch'. This ensures that #
# your local tags list is up-to-date and prevents the accumulation of tags that
# # no longer exist on the remote.
pruneTags = true

[receive]
# Verifies the integrity of all objects during data transfer operations like
# clone, helping detect corruption or tampering early.
fsckObjects = true

[branch]
# Configures `git branch` to sort branches by most recently used rather than
# alphabetically, making it easier to locate active branches.
sort = -committerdate

# Automatically sets up an upstream (merge) tracking branch when creating a new
# branch from a remote-tracking branch This allows 'git pull' and 'git push' to
# work without specifying the remote/branch
autoSetupMerge = true

[tag]
# Sort tags by the date they were created.
sort = taggerdate

[help]
# When a mistyped Git command closely resembles a valid one, this setting
# prompts the user with a suggestion before executing the corrected command,
# preventing accidental execution of unintended commands.
autoCorrect = prompt

[advice]
# Disables the hints shown by 'git status', such as suggestions for the next
# commands to run:
# (use "git add <file>..." to update what will be committed)
# (use "git restore <file>..." to discard changes in working directory)
statusHints = false

[grep]
lineNumber = true

[blame]
# The `ignoreRevsFile` makes `git blame` ignore certain commits.
# It points to a file that contains a list of commit hashes or revision
# ranges.
#
# This is useful in scenarios such as:
# - Automatically generated changes (e.g., formatting changes, code cleanup)
# - Bulk changes for reasons unrelated to the actual development of the code
#   (e.g., refactoring, dependency updates)
# - Avoiding noisy commits that can distract from meaningful line-by-line
#   changes and authorship.
ignoreRevsFile = .git-blame-ignore-revs

[color "branch"]
# Uses brighter colors for improved readability and visual comfort
remote = green
local = yellow
current = yellow reverse

[color "branch"]
# Uses brighter colors for improved readability and visual comfort
remote = green
local = yellow
current = yellow reverse

[color "diff"]
# Uses brighter colors for improved readability and visual comfort
frag = magenta bold
whitespace = red reverse
meta = yellow bold
new = green bold
old = red bold

[color "status"]
# Uses brighter colors for improved readability and visual comfort
untracked = cyan
changed = green
added = green

[alias]
# This alias simplifies the process of pulling changes by automatically stashing
# local changes, rebasing the current branch on top of the remote, and then
# reapplying the stashed changes, ensuring a clean and linear commit history.
up = pull --rebase --autostash

# Show details of the most recent commit or a specified object
s = show

# Commit all tracked changes
cia = commit -a

# Continue a rebase after resolving conflicts
rc = rebase --continue

# Amend the most recent commit with staged changes
amend = commit --amend

# Amend the most recent commit without changing the commit message
commend = commit --amend --no-edit

# Push commits to the remote repository
p = push

# Force push to the remote repository, overwriting history
pf = push --force

# Stage a specific file or files for commit
a = add

# Stage all changes (including deletions) in the working directory
aa = add -A

# Show a short summary of the working directory status
st = status -s

# Switch branches or restore working tree files
co = checkout

# List, create, or delete branches
b = branch

# Discard all local changes and reset to the latest commit on the current branch
rh = reset --hard HEAD

# Fetch and integrate changes from the remote repository
pl = pull

# Create, list, delete or verify a tag object
t = tag

# Show changes in the working directory relative to the last commit
d = diff HEAD

# Rebase
rb = rebase

# Reset
rs = reset

# Show staged changes that will be included in the next commit
dc = diff --cached

# Launch the configured diff tool to view changes
dt = difftool

# Show word-by-word diff of the working directory against the last commit
dw = diff --color-words HEAD

# Show word-by-word details of the most recent commit
sw = show --color-words

# Display the commit history
l = log

# Display commit history in a compact and decorated format
ls = log --pretty=format:"%C(yellow)%h\\ %ad%Cred%d\\ %Creset%s%Cblue\\ [%cn]" --decorate --date=short

# Show commit history with GPG signature verification and file change summary
logs = log --show-signature --stat

# Show full commit history with diffs
lp = log -p

# Apply changes introduced by existing commits
chp = cherry-pick

# Abort an in-progress cherry-pick operation
chpa = cherry-pick --abort

# Continue an in-progress cherry-pick after resolving conflicts
chpc = cherry-pick --continue

# Quit an in-progress cherry-pick without committing
chpq = cherry-pick --quit

# Skip the current commit during an in-progress cherry-pick
chps = cherry-pick --skip

# Show the absolute path to the root of the current Git repository
root = rev-parse --show-toplevel

[include]
# Load local configurations.
# This must remain at the end of the file to ensure that any local
# configurations can override the settings above.
# See: https://git-scm.com/docs/git-config#_includes
path = ~/.gitconfig.local