.gitconfig

# vim:tw=0:ts=2:sw=2:et:norl:ft=gitconfig
# Author: Landon Bouma (landonb @ retrosoft . com)
# Project: https://github.com/landonb/git-smart#💡
# License: MIT

# #######################################################################
# ***                            Overview                             ***
# #######################################################################

# USAGE: Read through the [alias]es defined below for a description of each.

# YOU/DEV: Put your user.* settings, private aliases, and whatever else you
# want in a separate, private config file, named .gitconfig.local, that's
# loaded last (at the end of this file, so it overrides anything herein).

# CONVENTION: Some commands work on branch(es) and remote(s) and will default
#             to the following unless you pass args indicating otherwise
#             (or unless the command otherwise deduces the remote name,
#             e.g., by using the remote indicated by the tracking branch).
#
# - Remote names:
#
#   'origin'      The default remote name assigned by `git clone`.
#                 Herein assumed to refer to repositories you control,
#                 e.g., if you fork a project, "origin" points to your
#                 fork on, say, GitHub. Or if you create a new project,
#                 "origin" refers to it.
#   'upstream'    The remote name used for the main project repository,
#                 e.g., if you fork a project, the "upstream" remote
#                 points to the main project repository. The name,
#                 "upstream", is not codified by any tools, GitHub,
#                 etc., it's just what I've seen used a lot in online
#                 document/blog posts/Q&As, so I think it's well-known.
#
#   'proving'     What I (lb) like to use instead of "origin", as in,
#                 where I prove my forked code works before submitting
#                 a pull request to the upstream project team.
#   'release'     What I (lb) prefer to use instead of "upstream", as
#                 in, the "release" remote points to the main project
#                 repository that pushes out the actual releases. (And if
#                 I create a new project, I name its remote "release".)
#                 - I like to avoid the term "origin" to indicate that
#                   I'm deliberate about the remote name, so there should
#                   be no confusion about what the remote represents.
#   'starter'     When I clone someone else's project, or if I fork a
#                 project, I name the project repository's remote "starter".
#                 That is, the "proving" and "release" remotes points to
#                 repositories under my control, but "starter" does not,
#                 and references the most-upstream remote.
#   'myclone'     When I fork a project but do not plan to contribute to
#                 it, I'll name the remote "myclone". The name is arbitrary,
#                 but using a name other than "proving" or "release" ensures
#                 the git-my-merge-status command will not incorrectly
#                 diagnose the state of my local working tree.
#
# - Branch names:
#
#   Most of the commands below work on the current branch, except
#   for git-since, which assumes there's a "release" branch; and
#   git-cleanup, which removes merged branches not identified as
#   a "core" branch, one of: liminal|proving|release|private|main|trunk|develop.
#
#   'release'     For any project I share/publish publicly, I always have
#                 at least a "release" branch. When I develop new code, I
#                 either commit directly to "release", or I'll use a feature
#                 branch (named something other than one of the core names)
#                 and later merge that work into release.
#
#   'private'     For any project I do not publish but that's private to
#                 me, I generally have just one branch that I name "private",
#                 mostly to remind me (when I run `git branch`) that the
#                 project I'm working on is a private project.
#
#   'proving'     For any public project under active develop, in addition
#                 to the "release" branch, I'll maintain a "proving" branch
#                 where I commit code under it's ready to be released. Other
#                 people might call the "proving" branch something different,
#                 such as "main", "trunk", or "develop", to name a few.
#
#   'main', 'trunk', 'develop'
#                 Similar in concept to 'proving'. While I don't use this
#                 branch name, it's recognized by at least a few commands,
#                 such as git-cleanup (below) and git-cleanbr (under bin/)
#                 that remove feature branches (but not any "core" branch).
#
#   'liminal'     As Wikipedia states, "In anthropology, liminality is the
#                 quality of ambiguity or disorientation that occurs in the
#                 middle stage of a rite of passage." I use the branch name
#                 "liminal" on branches that I push remotely but that I later
#                 rebase. That is, other developers should not base their
#                 work on this branch, but I'll eventually rebase it before
#                 merging it to the "proving" branch. The "liminal" branch
#                 is essentially a feature branch, but one that I push to a
#                 remote so that it's backed up.
#
#   'wip/YYYY-MM-DD-*'
#                 Used for [w]ork [i]n [p]rogress branches. While none of
#                 the commands in git-smart are concerned with WIP branches,
#                 some spun-off projects do (such as git-my-merge-status),
#                 so it's worthy of note.
#
#   'tip/YYYY-MM-DD-abcdef01'
#                 Used for tipped forks, also not a concern of git-smart,
#                 but recognized by git-my-merge-status, so also so noted.
#                 A "tip" branch is a branch of a forked project that's
#                 ahead of the upstream's main development branch, but
#                 that you don't except/want to submit as a pull request.
#                 Think unique features you add that you're certain don't
#                 belong upstream, or that you don't think an upstream
#                 maintainer will accept. As such, you'll periodically
#                 rebase your changes atop the upstream remote branch,
#                 say, 'refs/remotes/release/release'. You'll probably
#                 also not have a local main development branch (i.e.,
#                 you'll delete the "release" branch after cloning your
#                 fork, and you'll change the default branch on GitHub
#                 before deleting the "release" branch from there as well).
#                 - Tipping is a way to fork a project, and to make some
#                   changes without submitting an upstream pull request,
#                   but also to not publish a divergent "release" branch
#                   that you'd have to force-push to keep up to date. By
#                   using the "tip/YYYY-MM-DD-abcdef01" naming scheme,
#                   any time the upstream branch changes, you create a
#                   new tip branch, rebase your work, and publish a new
#                   tip. Obviously, this might be tedious if the upstream
#                   branch changes frequently, but I find myself only doing
#                   this on mostly stable projects that I've forked and need
#                   to tweak (such as my
#                     https://github.com/hotoffthehamster/click-hotoffthehamster
#                   forked project). Also, by following this workflow and
#                   naming scheme, we're broadcasting better what's going
#                   on (and avoiding new DEVs being misled by a 'release'
#                   branch that doesn't match the upstream project's).

# #######################################################################
# ***                       "Engage Your Core"                        ***
# #######################################################################

[core]
  # Configure the pager.
  # - Re: Not using `most`, not `less`, for the pager, because:
  #   - Using `most` looks a lot like using `less`, but note that `most`
  #     does not map Vim keys like `less` does. One might say that `most`
  #     isn't quite more than `less` so much as it is just neither `less`
  #     nor more. (By which I mean, I prefer `less` because I can use the
  #     same keys that Vim uses to browse and search.)
  #   - One possible advantage with `most` is to call it with some options,
  #     e.g., use `+s +'/---'` to advance `most` to the first change in the
  #     diff (effectively just skipping the first two lines of the diff...).
  #     E.g.,
  #           pager = most +s +'/---'
  #     But, like I said, I'd rather have Vim-like search and navigation bindings.
  # - Setting the pager configures `git diff|log|mergetool` to use `less`
  #   to display text.
  # - Use `-R`, so `less` interprets ANSI color codes, otherwise they're
  #   shown raw, e.g., "[ESCapes234".
  pager = less -R

  # Configure the editor.
  # - Similar to how Vim defers to another application for paging, Vim also
  #   defers to another application for editing, e.g., what's invoked when
  #   you run `git ci -v`, for one, or `git rebase -i ...`, for another.
  # - Git defaults to using the (Bash) "EDITOR" environment variable to
  #   determine which application to run. So generally you don't need to
  #   specify it here, unless you want to do something special.
  #   - E.g., for a while, I had Vim startup issues when run from git, so
  #     I just made a Bash script that essentially called `vim --noplugin`,
  #     and then I wired it here, e.g.,
  #         editor = ~/.local/bin/git-vim
  #     or even just:
  #         editor = vim --noplugin
  #     but then I got off my tuchus and fixed my Vim scripts.
  #     So I'm not setting `editor` here.
  #     - You should rely on the EDITOR environ.
  # SKIPPING:
  #   editor = ...

  # Configure git's taste for whitespace.
  # - I like a blank line at the end of every file. This ensures that when I
  #   jump the cursor to the end of a file, it then rests at the first column
  #   of a new line, as opposed to being placed in the last column of some
  #   unknown-length line of characters.
  #   - But git complains when you add files that have a trailing new line.
  #       So tell git not to worry or bark at you.
  #   - Ref:
  #       https://stackoverflow.com/questions/27059239/git-new-blank-line-at-eof
  #   - See also:
  #       whitespace = cr-at-eol
  whitespace = -blank-at-eof

# #######################################################################
# ***                          git colorful                           ***
# #######################################################################

# - We could enable color one by one, e.g.:
#
#     branch = auto
#     diff = auto
#     status = auto
#     interactive = auto
#
#   Or we could enable 'em all at once, e.g.:
#
#     ui = auto
#
# - Instead of `auto`, we could use `always`, so that
#   piping pipes colors, e.g.,
#
#       git config color.ui always
#       git log --stat | less  # So colorful!
#
#   But then -- *caveat* -- you'd want to disable color when parsing output,
#   lest the color codes break your code, i.e., ruin string comparisons, etc.
#   Which you could work around with a one-off config override, e.g.,
#
#       git -c color.ui=off ...
#
#   or by using the global no-color option:
#
#     git --no-color ...
#
#   but that's just too messy.
#
#   Going with 'auto' seems like a happy place.

[color]
  ui = auto

# 2020-02-09: I added these colors years ago. Source unknown.
# - But they've withstood the test of time. They look nice.

[color "branch"]
  current = green bold
  local = green
  remote = red bold

[color "diff"]
  meta = yellow bold
  frag = magenta bold
  old = red bold
  new = green bold

[color "status"]
  added = green bold
  changed = yellow bold
  untracked = red

# #######################################################################
# ***                             advice                              ***
# #######################################################################

# "I'm all good, thanks."
#
# Quell Git advice, e.g.,
#
#   $ git add
#   Nothing specified, nothing added.
#   hint: Maybe you wanted to say 'git add .'?
#   hint: Turn this message off by running
#   hint: "git config advice.addEmptyPathspec false"
[advice]
  addEmptyPathspec = false

# #######################################################################
# ***                              diff                               ***
# #######################################################################

[diff]
  # Use the 'minimal' diff algorithm to achieve desired diff behavior.
  # - For example, in a reST file containing section headers, like "#######",
  #   I cut and pasted a big block of text, and the default greedy git diff
  #   algorithm, myers, shows the move as a bunch of small deletions and
  #   insertions. (But if you diff using `meld`, you see one big deletion
  #   and one big insertion.) We can use a different algorithm to make the
  #   diff easier to parse.
  # - Choices:
  #    default    aka "myers".
  #    minimal    Spend extra time to ensure smallest possible diff produced.
  #    patience   Use "patience diff" algorithm when generating patches.
  #    histogram  This algorithm extends the patience algorithm to
  #               "support low-occurrence common elements".
  algorithm = minimal

  # Hide the path prefix from git-diff output.
  # - If you'd like to be able to double-click and copy-paste from git-diff
  #   output, suppress the awkward "a/" and "b/" path prefixes.
  #   - I think these prefixes are holdovers from old SCMs. See:
  #       https://stackoverflow.com/questions/6764953/
  #         what-is-the-reason-for-the-a-b-prefixes-of-git-diff
  noprefix = true

  # NOTE: The diff.noprefix option does not apply to the 'a/' and 'b/'
  #       prefixes shown in interactive patch mode, i.e., on `git add -p`.
  # - The `--no-prefix` option is documented in `git-diff --help`, but it's not
  #   found in `git-add --help`. (So I'm guessing there's no builtin mechanism.)
  # - But don't fret! git-smart has the answer!
  #   - The `diff-filter-garden` script shows how to strip the 'a/' and 'b/'
  #     prefixes -- but it also adds a visual break between interactive patch
  #     hunks, which you may or may not like. So if you just want the prefix
  #     stripping, you'll have to pull it out yourself!
  #     - Look for and copy the interactive.diffFilter setting from the
  #       `.gitconfig.local.example` file to your own config to try it out.

# A more informative binary diff, how brilliant!
# - Found solution to more meaningful PDF diff at:
#   https://superuser.com/questions/706042/how-can-i-diff-binary-files-in-git
# - See the `*.bin diff=bin`, etc., rules in ~/.config/git/attributes, and ref:
#   man 5 gitattributes

[diff "bin"]
  textconv = hexdump -v -C

[diff "pdf"]
  textconv = pdfinfo

[diff "zip"]
  textconv = unzip -v

# #######################################################################
# ***                             merge                               ***
# #######################################################################

# *** VIM-MERGETOOL

# (Skip this section unless you want to know all about vim-mergetool!)

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# 2021-02-15: I tried using git-mergetool years ago, but it never stuck.
#
# - I didn't like that the default view (whether Vimdiff or meld) shows
#   you three files, but that the automatically resolved hunks still show
#   up in the diff (which makes finding and resolving the unresolved
#   conflicts more difficult, and less obvious). So it felt like I was
#   doing *more* work than if I just edited the conflict file directly
#   (and removed the <<< === >>> conflict delimiters manually, too).
#
#   - E.g., you'll see the "ours" version (mainline branch) on the left,
#     and the "theirs" version on the right (e.g., your feature branch),
#     and the merged result in the middle.
#
#   - But, unfortunately, the merged result highlights hunks for conflicts
#     that Git has already resolved, because those hunks still differ from
#     either or both the files on the left and right. That's just how such
#     a three-way works out!
#
#   - To see for yourself: `git mergetool --tool=meld`.
#
# But today I finally dug a little deeper, and I found the perfect solution!
#
# - Check out vim-mergetool, which solves the problem by not bothering with
#   the $LOCAL or $REMOTE versions. Rather, it uses the conflict file, which
#   git-rebase leaves for you to fix, and makes a copy. Then, it removes the
#   "their" hunks from the first file, and removes the "our" hunks from the
#   second, copied, file; and also the <<< === >>> delimiters from both.
#   Finally, it shows you the diff between those two files, with the first,
#   editable "ours" file on the left, and the unmodifiable "theirs" version
#   on the right. How simple is that, and how perfect! You only see the
#   unresolved conflicts, and you don't have to bother with the delimiters,
#   either.
#
# - See next for the vim-mergetool config, followed by discussion of the
#   other mergetools, and finally, after that, more about (a lot more about)
#   vim-mergetool usage (though not as long as the vim-mergetool README! =⟩
#   (as if I'm one to talk!)).

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# You'll need vim-mergetool for the following settings:
#
#   https://github.com/samoshkin/vim-mergetool
#
# Oh, and you'll need to use Vim. And I realize this ~/.gitconfig
# is generally editor-agnostic, but not for this setting!

# PRIMARY USAGE: `git mergetool`

[merge]
  tool = vim_mergetool
  conflictstyle = diff3

[mergetool "vim_mergetool"]
  cmd = vim -f -c "MergetoolStart" "$MERGED" "$BASE" "$LOCAL" "$REMOTE"
  # "When trustExitCode = false, checks if MERGED file was modified.
  #  When trustExitCode = true, checks exit code of merge tool process."
  trustExitCode = true

[mergetool]
  # Tell `git mergetool` to remove its intermediate files when finished.
  keepBackup = false

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# *** Other mergetool tools.

# Some other merge tools that I demoed:
#
#   [merge]
#     tool = meld
#
#   [merge]
#     tool = vimdiff
#     conflictstyle = diff3
#
#   # https://github.com/tpope/vim-fugitive
#   [merge]
#     tool = fugitive
#     conflictstyle = merge
#
#   # "A better vimdiff mergetool for Git" circa 2012.
#   #  See: git-smart/bin/diffconflicts
#   [merge]
#     tool = diffconflicts

# There are two configurations that make the most sense with meld:
#   [mergetool "meld"]
#     cmd = meld "$LOCAL" "$BASE" "$REMOTE" --output "$MERGED"
#     cmd = meld "$LOCAL" "$MERGED" "$REMOTE" --output "$MERGED"
# The second one, using $MERGED, is nice because it contains resolved
# conflicts that Git could figure out automatically. But that resolved
# code still diffs against either the $LOCAL or $REMOTE. As such, it's
# not exactly obvious when you're done, e.g., you won't end up with all
# three files in meld looking the same and not having any conflicts.
# Instead, you'll have to manually inspect all the diffs, decide that
# you're done and there's nothing more to edit, and then save and quit.

# The vimdiff tool gives a similar experience to meld in terms of what you
# see, and needing to mentally parse conflicts Git has already resolved.
#   [mergetool "vimdiff"]
#     cmd = vimdiff --noplugin "$LOCAL" "$MERGED" "$REMOTE"

# vim-fugitive can also mergetool (what can't it do! love that plug). But
# it suffers from same issues as `meld` and `vimdiff`, and shows you the
# automatically resolved conflicts mixed in with those that are unresolved.
# - See this post for more help:
#     https://vi.stackexchange.com/questions/3985/git-mergetool-vimdiff-command
#   The basic suggestion is to call Gdiffsplit when Vim starts, e.g.,:
#     cmd = vim "+Gdiffsplit" $MERGED
#   but I like also calling `Git mergetool`.
# Consider:
#   [mergetool "fugitive"]
#     cmd = vim "+Gdiffsplit" "+'Git mergetool'" $MERGED
# - Hints:
#   - The + is like -c, and runs the command.
#   - The `Gdiff[split]` (from vim-fugitive) starts the diff.
#   - The `Git mergetool` (from vim-fugitive) populates quickfix with conflicts.
#   - You'll see all the conflicts, including what Git has already resolved.
#   - You can navigate with vim-unimpaired's `[Q` to go to first quickfix item.
#     (I expected `[q` to also work, but alas, not for me (though maybe my fault)).

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# *** vim-mergetool in-depth.

# *** STARTING MERGETOOL
#
# If you've rebased and have conflicts, you can start from a terminal:
#
#     git mergetool
#
# Alternatively, open a file that has conflicts and run vim-mergetool:
#
#     :MergetoolStart

# *** RUNTIME USAGE
#
# - You can still run `:Git mergetool` (from vim-fugitive) if you want
#   to see conflicts in quickfix, but `:MergetoolStart` already folds
#   the file and shows only the remaining, unresolved conflicts.
#
# - You can use [c and ]c to jump between conflicts.
#
# - If you run `:Git mergetool`, [Q and ]Q work (and maybe [q and ]q ?).
#
# - The right-hand side is the "theirs" commit, aka your feature branch.
#
# - The left-hand side is the "ours" commit, aka the mainline (e.g., if
#   you had called `git rebase upstream/develop`, then 'upstream/develop').
#
# - The right-hand side is read-only, so of the two built-in Vimdiff
#   commands, `:diffget` and `:diffput`, you can only `:diffget` into
#   the left-hand window, where has the focus to start.
#
#   - Type `do` to get the diff chunk from the right-hand side. (Think
#     mnemonic *diff obtain* (because `dg` is used by another command.)
#
#   - If you happen to move the cursor to the right-hand side,
#     use `dp` to *put* a diff chunk into the left-hand buffer.

# *** FINISHING MERGETOOL

# - You can `:MergetoolStop` when finished, and you'll be prompted
#   to save changes or not. Answer yes and mergetool will accept
#   your changes and stage the file. Or answer no and mergetool
#   will revert the file, so that it includes the original
#   unresolved changes (both sides' hunks and hunk delimiters).
#
#   If you just want to save and have the file staged, you can
#   skip `:MergetoolStop` and just write the left-hand file
#   and quit, and mergetool will silently process the file.
#
# - If you realize you made a mistake after saving or otherwise
#   telling mergetool to accept the changes, you can revert the
#   file using the checkout command, so you can merge again. E.g.,
#
#     git checkout -m -- {file}
#
#   The -m option will unstage the file and revert it to the
#   unresolved state with the unresolved hunks. (Or you might
#   be able to `git rebase --abort` and start the rebase over,
#   but `git co -m {file}` is more to the point.)

# *** HOW MERGETOOL PREPS

# - Note that the left-hand buffer is the original source file (that will
#   be added to staging) and is not a copy like the right-hand buffer. So
#   once :MergetoolStart has started and you're looking at the diff, the
#   file is already changed.
#
#   - As such, if you undo (e.g., press Ctrl-z) in the original file
#     buffer, you will revert the changes that vim-mergetool made, and
#     the file will be its original self, with both the "our" and "theirs"
#     hunks, and with the <<< === >>> delimiters. Just like Vim left it
#     after the rebase.
#
#   - But if you start the merge, then save and exit immediately without
#     editing, you'll effectively have accepted all the "our" changes,
#     and ignored all the "theirs".
#
#   - Or, you can use `:MergetoolStop`, which will ask if the edit was a
#     success, and you can answer "no" to revert the file, or "yes" to
#     add the file to staging (and then you can continue the rebase,
#     e.g., run `git rebase --continue`, perhaps).

# *** FOLDING REMINDER

# - Be aware that you might want to expand folds (zR) while diffing,
#   especially after editing, as changes you make might be clipped
#   or hidden by a fold.

# *** QUITING REMINDER

# - You can quit quickly by saving the file, and then using `:qa`
#   to close all windows and quit Vim.
#
#   - Or, to not save, `:qa!` quits all windows and Vim, NQA.
#
#     You can also use `ZQ` to quickly close and quit each window
#     individually.
#
#   (The author reminds themselves this because they mostly use
#    non-standard <Alt-f e> and <Alt-f x> mappings to close all
#    files and quit Vim (remnants of my Windows days, what can
#    I say). And while I use `:q` or `ZZ` aplenty, I cannot say
#    the same for `:qa` or `ZQ`.)

# *** MERGING *BOTH* HUNKS

# - Note that Vim has not plumbed an "accept both ours and theirs"
#   option. I guess because it's rare? Though I think I've combined
#   quite a few diff hunks in my devtime. Seems like it'd be useful.
#
#   - To combine hunks, there are two approaches I find the fastest:
#
#     - One option is to copy the left hand hunk, and then obtain the
#       right-hand hunk (which overwrites the left-side), and paste.
#
#     - Another option is to use undo to revert the vim-mergetool
#       edits to the left-hand buffer, and then edit manually,
#       possibly using \dx (custom mapping; or see the regex below)
#       to remove the <<< === >>>s.
#
#   - Approach #1: Yank, Obtain, Put:
#
#     - Manually copy the hunk on the left, then press `do` to
#       'obtain' the other hunk. Then paste what you had just
#       copied. This will also have removed the <<< === >>>
#       delimiters.
#
#       - To copy, probably count lines, then with cursor on the
#         first line (in any column), type number of lines minus
#         one (because the first line is inherently included), press
#         `y`, and then either Down arrow or `j`. E.g., if the "ours"
#         hunk is 5 lines, press `4yj`, then `do`, then `p` to put
#         the yanked hunk.
#
#   - Approach #2: Manually Edit:
#
#     - You could use the undo trick after starting the vim-mergetool
#       to bring back the conflict hunks. But it's probably easier to
#       just edit the file normally, and to use a regex substitute to
#       find conflicts to edit and to remove the <<< === >>> delimiters.
#
#     - Using the following :global command removes all conflict
#       delimiters (the :g will run `d` on all matching lines):
#
#         :g/^<\{7}\|^|\{7}\|^=\{7}\|^>\{7}/d
#
#       - Thanks to tecfu for that command!:
#         https://github.com/tpope/vim-fugitive/issues/1022
#
#     - Alternatively, you can run the substitute command
#       to the same effect:
#
#         :.,$s/^\(<\{7}\|^|\{7}\|^=\{7}\|^>\{7}\).*\n//g
#
#     - Or, if you want to be prompted for each match, run:
#
#         :.,$s/^\(<\{7}\|^|\{7}\|^=\{7}\|^>\{7}\).*\n//gc
#
#     - I like the confirmational substitute command (the last
#       one) so much that I made a home for it at `\dx`, e.g.,:
#
#         autocmd DiffUpdated * if &diff | nnoremap <leader>dx
#           \ :.,$s/^\(<\{7}\\|^\|\{7}\\|^=\{7}\\|^>\{7}\).*\n//gc<CR>
#
#       - Then, e.g., if I started :MergetoolStart but see that I need
#         to manually combine hunks, I could Ctrl-z to undo the initial
#         merge step, and then I'd press \dx to jump to and remove each
#         set of hunk delimiters, editing and resolving each pair of
#         conflicting hunks along the way.

# - And that's `git mergetool` using `vim-mergetool` explained in 300 lines!

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# #######################################################################
# ***              Ever-expanding Git Aliases Collection              ***
# #######################################################################

# NOTE: The aliases are split across multiple groups listed below,
#       hopefully to make the remainder of the file easier to read
#       and maintain.

# NOTE: The only way to pass a global option to git is to shell out. AFAIK.
#
#       So, e.g., instead of a simple alias such as:
#
#         br = branch
#
#       You'll see a slightly more complicated alias, e.g.,
#
#         br = !git --no-pager branch

# TRICK: You can wrap shell code in an anonymous Bash function
#        when you need to shell out, to have access to, well,
#        at least the 'local' function (which can only be used
#        in functions).
#        - I read that you need to use an anonymous function to
#          access command line variables and shell expansion.
#          But I have aliases that shell out without a function
#          wrapper, and they access numbered arguments
#          ($1, $2, etc.) just fine.
#       - E.g., it's the difference between writing this:
#           my-alias = ! echo Hello
#         and this:
#           my-alias = "! f() { echo Hello; }; f"
#         but not this (syntax error without quotes):
#           my-alias = ! f() { echo Hello; }; f
#       - Here's the article, which is good in its own right:
#           https://www.atlassian.com/blog/git/advanced-git-aliases
#       - Nonetheless, you'll see some shell code below wrapped in a
#         function, and some code not. Just kinda depends.
#       - Oh! I think unwrapped functions get arguments at the end, always,
#         e.g., given the alias
#           view = !echo \"FOO $@ BAZ\"
#         then
#           $ git view bar
#           FOO bar BAZ bar
#         So use the wrapper when necessary, e.g.,
#           view = "! f() { echo \"FOO $@ BAZ\"; }; f"
#         then it works more like one might expect:
#           $ git view bar
#           FOO bar BAZ
#
# NOTE: Shell code is run by POSIX (e.g., dash), not Bash, so
#       avoid constructs such as [[ ]] unless you invoke Bash.
#       - E.g., this is wrong:
#           test1 = "! f() { [[ -z \"$1\" ]] && echo 'Z!' || echo 'n.'; }; f"
#         Because it won't be run by Bash, and will throw an error, e.g.,
#           $ git test1 "sdff"
#            f() { [[ -z "$1" ]] && echo 'Z!' || echo 'n.'; }; f: 1:
#             f() { [[ -z "$1" ]] && echo 'Z!' || echo 'n.'; }; f: [[: not found
#           n.
#         But you could instead shell out your shell code to Bash, e.g.,
#           test2 = ! "/usr/bin/env bash -c \"f () { [[ -z \\\"$1\\\" ]] && echo Z || echo n; }; f\""
#         or you could just rewrite it to be POSIX-compliant, e.g.,
#           test3 = "! f() { [ -z \"$1\" ] && echo 'Z!' || echo 'n.'; }; f"
#
# NOTE: One final shell code note: You need to \-delimit line breaks;
#       and you need to use a semicolon after each line (i.e., you
#       cannot rely on newlines to signal the parser what's what).

# NOTE: Within each [alias] section, I've arranged my My Most Popular Git
#       Aliases up top (those that I use the most), above a mini-ruler:
#
#       # -------

# #######################################################################
# ***                     Branch Command Aliases                      ***
# #######################################################################

[alias]
  br = !git --no-pager branch
  # If you don't want coloration/coloring, and if you don't want the ` *`
  # before the current branch, or `  ` before other branches, try:
  #   br = !git --no-pager branch --format='%(refname:short)'

  # Years later: There's no `git b`, so why not print branch list,
  # at least until a better `git b` emerges.
  b = br

  # - Use `git brs` to show all branches, including remote branches.
  # - git-brs is inherently aliased because found on PATH.
  #    brs = !${GITSMART_BIN:-${HOME}/.local/bin}/git-brs \"$@\"

  # -------

  # Bro!
  bro = "! f () { \
    local tracking_br_rem tracking_remote; \
    tracking_br_rem=$(git rev-parse --abbrev-ref --symbolic-full-name @{u}); \
    if [ $? -ne 0 ]; then \
      >&2 printf '%s\\n' 'ERROR: Set tracking branch to use this command'; \
      return 1; \
    fi; \
    tracking_remote=$( \
      printf '%s' \"${tracking_br_rem}\" \
      | /usr/bin/env sed -e 's#/.*$##' \
    ); \
    \
    printf '\\n'; \
    printf '%b\\n' \"\\\\e[31mLocal branches\\\\e[0m\"; \
    printf '%b\\n' \"\\\\e[31m--------------\\\\e[0m\"; \
    git --no-pager branch -vv; \
    printf '\\n'; \
    printf '%b\\n' \"\\\\e[31mRemote branches (on '${tracking_remote}')\\\\e[0m\"; \
    printf '%b\\n' \"\\\\e[31m---------------\\\\e[0m\"; \
    git --no-pager ls-remote --heads ${tracking_remote} \
      | /usr/bin/env sed 's?.*refs/heads/??' \
      | /usr/bin/env sed -e \"s/^/\\ \\ /\" && \
    printf '\\n'; \
  }; f"

  brs-all = !git --no-pager branch -avv
  bra = !git --no-pager branch -avv

  # Delete merged branches except any conventionally-named branch (e.g., the
  # main development branch, what I call "proving" or others might call "main";
  # the release branch, often called "release"; or a "private" branch, which is
  # the branch label I use in private repositories I don't publish), and not
  # the current branch, either.
  #   https://gist.github.com/jantimon/5b9fd9330f38d076a374c03fcbb788e1
  # (jantimon/{} is technically not licensed: No license info.)
  cleanup = "! f () { \
    local tracking_br_rem tracking_remote; \
    tracking_br_rem=$(git rev-parse --abbrev-ref --symbolic-full-name @{u}); \
    if [ $? -ne 0 ]; then \
      >&2 echo 'ERROR: Set tracking branch to use this command'; \
      return 1; \
    fi; \
    tracking_remote=$(printf '%s' \"${tracking_br_rem}\" | /bin/sed -e 's#/.*$##'); \
    \
    git remote prune ${tracking_remote} && \
    git branch --no-color --merged \
      | egrep -v '(^\\*liminal|proving|release|private|main|trunk|develop)' \
      | xargs git branch -d; \
  }; f"

  # Show the current branch name.
  # (I added this alias years ago, but I hardly use it.
  #  - I usually check for the branch name using `git br`, unless I need to
  #    script it, and then I just call rev-parse directly.
  #    - I would have guessed that 'br' would be faster to type the 'cur',
  #      but they're about the same.
  #    - I think that `git br` is more versatile -- in addition to seeing what
  #      branch the tree is on, it also reminds me of what other branches exist.
  #    - The only reason I see to keep this alias is as a rev-parse usage example.)
  # Weird: git rev-parse defaults --abbrev-ref per core.warnAmbiguousRefs, but
  #          rev-parse --abbrev-ref HEAD
  #        on Linux returns the --abbrev-ref=loose form, e.g., "my_branch", but
  #        on macOS it runs like --abbrev-ref=strict, e.g., "heads/my_branch".
  #        We want to be consistent, and to show the simpler name.
  # 2022-10-05: This is poorly-named. I didn't recall this existed...
  cur = rev-parse --abbrev-ref=loose HEAD
  # 2022-10-05: Until I devise a better name, perhaps a TAB-completion reminder:
  cur-br = rev-parse --abbrev-ref=loose HEAD
  # FIXME/2022-10-05 20:07: Find a better alias, and consolidate previous 2 commands.

  # -------

  # - Use `git-cleanbr` to delete a branch locally and on the remote,
  #   after switching to 'develop' or another branch.
  # - git-cleanbr is inherently aliased because found on PATH.
  #    cleanbr = !${GITSMART_BIN:-${HOME}/.local/bin}/git-cleanbr \"$@\"

  # - Use `git-cob` to checkout a branch from an existing remote for which
  #   there is no local tracking branch, but for which there are multiple
  #   remotes with the same-named branch, and you cannot simply
  #   `git checkout <branch>` but have to be remote-specific.
  # - git-cob is inherently aliased because found on PATH.
  #    cob = !${GITSMART_BIN:-${HOME}/.local/bin}/git-cob \"$@\"

  # - Use `git-coc` to create a new branch, switch to it, and push it.
  # - NOTE: I tried doing this inline, e.g.,
  #     coc = !git branch ${1} && git checkout ${1} && git push ${2:-origin} ${1} -u
  #   but git puts the args after the command, so the git push ends up looking like:
  #     git push ${2:-origin} ${1} -u ${1}
  #   which obviously fails. So shell out!
  # - git-coc is inherently aliased because found on PATH.
  #    coc = !${GITSMART_BIN:-${HOME}/.local/bin}/git-coc \"$@\"

  # - Delete branches that are "gone" on the remote.
  #   - You can find tracking branches with missing remote branches via:
  #       git branch -vv --no-color | grep ': gone]'
  #     and then you can big-D delete them thusly:
  #       git branch -D <branch>
  # - git-gone is inherently aliased because found on PATH.
  #    gone = !${GITSMART_BIN:-${HOME}/.local/bin}/git-gone \"$@\"

  # -------

  # Upstream branch name. From:
  #   https://gist.github.com/pksunkara/988716#file-config-L86
  # (pksunkara/988716 is technically not licensed: No license info.)
  #
  # SAVVY/2024-03-28: The git-rev-parse error message varies.
  # - If there's no upstream configured, it'll print:
  #     fatal: no upstream configured for branch 'liminal'
  # - But if the upstream is no longer valid, e.g., deleted branch, prints:
  #     @{u}
  #     fatal: ambiguous argument '@{u}': unknown revision or path not in the working tree.
  #     Use '--' to separate paths from revisions, like this:
  #     'git <command> [<revision>...] -- [<file>...]'
  #   In which case set a new upstream or run `git branch --unset-upstream`.
  #   - If you really need to know the value, look in the config:
  #       git config branch.<name>.merge
  #       git config branch.<name>.remote
  upstream = !git rev-parse --abbrev-ref --symbolic-full-name "@{u}"
  # Number of commits ahead or behind upstream branch. From:
  #   https://gist.github.com/pksunkara/988716#file-config-L260-L261
  ahead = !git rev-list --right-only --count $(git upstream)...HEAD
  behind = !git rev-list --left-only --count $(git upstream)...HEAD

# #######################################################################
# ***                         Logging Aliases                         ***
# #######################################################################

# A few of the --pretty git log format options:
#
#   %Cred     red text
#   %C(cyan)  Choose from: (normal, black, red, green, yellow, blue, magenta, cyan and white)
#   %h        abbreviated commit hash
#   %Creset   reset text color
#   %x0       print a byte from hex code (09: \t)
#   %an       author name
#   %x09      TAB
#   %ad       author date (format respects --date= option)
#   %x09      TAB
#   %d        ref names, like the --decorate option of git-log(1)
#   %s        subject
#   %<(<N>[,trunc|ltrunc|mtrunc]) make the next placeholder take at least N columns...
#     * 79c812f My Name  Fri Mar 1q0 17:05:27 2017  Update README.
#     * 2deef48 My Name  Thu Mar 9 13:02:57 2017 Fix something.
#     %<(24) is 24 chars for the "Fri Mar 10 17:05:27 2017" date. %>(24) to right justify.
#   If you add a ` ` (space) after % of a placeholder, a space is inserted immediately
#   before the expansion if and only if the placeholder expands to a non-empty string.

[alias]
  # Use `git l` to show the latest log message.
  # - (I tried other, longer names, such as `last`, `l1`, and `l`.
  #    But I like 'l' the best.
  #   - I like 'last' because it's descriptive, and the user probably doesn't
  #     have to guess what it does -- but it's annoying to type an 'a' after
  #     an 'l' (such a stretch across the keyboard!).
  #   - I like 'l1' because it's short, and it has a good pneumonic --
  #     1 log record, or 'l1' (well, '1l', I suppose, but whatever).
  #   - And I like 'l' because it's also short -- but I don't normally like
  #     single character abbreviations, because it makes searching more
  #     difficult (there are usually tons of false-positives to sift through).
  #     Also, I don't like to use a coveted single character abbreviation
  #     unless I think it'll be well-used.
  #   - In this case, with 'l', I do like the single character -- it's quick
  #     to type, and it's not like this single character appears any place
  #     other then here (so there's no grep-pollution to worry about). Also,
  #     I can also use the pneumonic of wanting one log record: And what 1
  #     character does the word 'log' start with? It's an 'l'! Finally, I
  #     think I will use this option frequently (I've already started),
  #     so let's go ahead and use up a single character alias! Worth it!!)
  #  l = !git --no-pager log -1
  l = "! f() { git --no-pager log -${1:-1}; }; f"
  l1 = "! f() { git --no-pager log -1; }; f"
  l2 = "! f() { git --no-pager log -2; }; f"
  l3 = "! f() { git --no-pager log -3; }; f"
  l4 = "! f() { git --no-pager log -4; }; f"
  l5 = "! f() { git --no-pager log -5; }; f"
  l6 = "! f() { git --no-pager log -6; }; f"
  l7 = "! f() { git --no-pager log -7; }; f"
  l8 = "! f() { git --no-pager log -8; }; f"
  l9 = "! f() { git --no-pager log -9; }; f"

  # Git command to show tag creation dates.
  # - Optional: Add --graph to see branching lines. E.g.,
  #     `git tags --graph`
  tags = \
    log \
      --date-order \
      --tags \
      --simplify-by-decoration \
      --pretty='format:%C(green)%ad %C(red)%h %C(reset)%D' \
      --date=short

  tags-match = "! f() { \
    git tag --format=\"%(objectname:short) %(refname:short)\" --list \"$@\"; }; f \"$@\""

  # USAGE: Without params, defaults to upstream remote,
  # and leads with the remote name, e.g.,:
  #     $ git tags-remote
  #     From git@github.com:thegittinsgood/easy-as-pypi.git
  #     555e9969250d391e88d189ca17f60723376fcb17	refs/tags/1.0.1
  #     ...
  # - If the upstream branch is local, prints local tags, e.g.,
  #     $ git tags-remote
  #     From .
  #     555e9969250d391e88d189ca17f60723376fcb17	refs/tags/1.0.1
  # USAGE: With single param, prints tags for that remote,
  # and leads without the remote name (leads with nothing), e.g.,
  #     $ git tags-remote publish
  #     555e9969250d391e88d189ca17f60723376fcb17	refs/tags/1.0.1
  # - Note that multiple params always outputs nothing (and exits 0)
  #   unless maybe *I'm doing it wrong*. I thought maybe Git would
  #   output shared tags (union) from multiple remotes, but that's
  #   not it. So guessing it's just nothing, for real's.
  tags-remote = "ls-remote --tags"

  # -------

  # Show just the date of the latest commit.
  d1 = "! f() { git --no-pager log -1 --format=%cd --date=format:%Y-%m-%d; }; f"

  # -------

  # Show how many times each file has been edited, aka churn.
  #
  # - Show check for the whole repo:
  #
  #   $ git churn
  #
  # - Show churn for specific directories:
  #
  #   $ git churn app lib
  #
  # - Show churn for a time range:
  #
  #   $ git churn --since='1 month ago'
  #
  # - Obvi., you can pass any git-log argument to churn.
  #
  # - Credits: Written by Corey Haines.
  #            Scriptified by Gary Bernhardt.
  #            Hacked by me (moved `sort -g` before `awk`, and split long line).
  churn = ! \
    git --no-pager log --all -M -C --name-only --format='format:' \"$@\" \
    | sort \
    | grep -v '^$' \
    | uniq -c \
    | sort -g \
    | awk 'BEGIN {print "count\tfile"} {print $1 \"\t\" $2}'

  # -------

  # Use `git lg` to show a very concise single-line log history.
  #
  # - Shows one log entry per line formatted like:
  #
  #   * HASH - DESCRIPTION (X days ago) <AUTHOR>
  #
  #   E.g.,
  #
  #   * acbd1234 - Docs: Update README. (4 days ago) <Your Name>
  #
  # - Thanks to:
  #
  #   https://www.leaseweb.com/labs/2013/08/git-tip-beautiful-colored-and-readable-output/
  lg = \
    log --graph --abbrev-commit --date=relative \
        --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'

  # -------

  # Use `git lg1` to see the best representation I could make of the `tig` log view.
  #
  # STYLE: Prefer `%C(foo)` to `%Cfoo` for readability.
  # INFO.: `less -R` required here, but not if you paste this command to your terminal.
  lg1 = "! f() { \
    git \
      --no-pager \
      log \
      --color=always \
      --date=\"format:%a %F %H:%M %z\" \
      --pretty=\"format:%h %C(blue)%cd %C(green)%<(22)%an%C(reset)%C(blue)o%C(reset)%C(red)%d%C(reset) %s\" \
      --graph | less -S -R; \
  }; f"
  # Hint:
  #
  #     --color=always        Because of the |pipe.
  #
  #     --date="format:..."   Pairs well with %cd
  #       %a %F %H:%M %z        E.g., "Sat 2020-11-21 16:58 -0600"
  #
  #     --pretty="format:..." I got the format looking almost like `tig`,
  #                             but tig might be doing something custom. I do
  #                             not see how to generate a similar graph column.
  #       %Cblue              Blue foreground color
  #       %Cgreen             Green foreground color
  #       %Cred               Red foreground color
  #                             Note: %Cblue, %Cgreen and %Cred all I see
  #                             defined in man git-log, but %Ccyan works, or
  #                             even %C(cyan) -- +1 parens, it's easier to read.
  #       %Creset             Resets color
  #       %<(22)              Right-pads with spaces to 22-characters
  #       %h                  Abbreviated commit hash
  #       %cd                 Committer date (format respects --date= option)
  #       %an                 Author name
  #       o                   You'll see in `tig`, part of its custom --graph
  #       %d                  Ref names, like the --decorate option of git-log(1)
  #       %s                  Subject
  #
  #     --graph               Draws graphical rep. of history on left hand side;
  #                             not quite like tig, which draws history after
  #                             the author's name and before the suject, not sure
  #                             how it does it.
  #
  #     | less -S             -S, aka --chop-long-lines, to not wrap lines
  #     | less -R             -R, or --RAW-CONTROL-CHARS: “Like -r, but only ANSI "color"
  #                                escape sequences are output in "raw" form. Unlike -r,
  #                                the screen appearance is maintained correctly in most
  #                                cases.”

  # -------

  # Use `git log1` to show exclusive history for the current branch.
  #
  # - Shows one log entry per line, formatted like:
  #
  #   * HASH AUTHOR Mon Jan 01 00:00:00 2001  (HEAD -> my-branch)DESCRIPTION
  #   * HASH AUTHOR Mon Jan 01 00:00:00 2001  DESCRIPTION
  #   * ...
  #
  # - HINT: %C(auto) uses colors like git-log normally does (e.g., per color.ui).
  #
  # - HINT: %+s will add a linefeed between meta and subject.
  #
  # - NOTE: I cannot get a space between the %D ref name and the %s subject. Ah, well.
  log1 = \
    log --graph --abbrev-commit --date=local --decorate \
        --pretty="%C(yellow)%h%x09%C(cyan)%<(12)%an%x09%C(blue)%>(24)%ad%C(auto)%x09%D%s"

  # -------

  # Use `git logs` to show more inclusive history than `git logs`.
  #
  # - It looks similar to `git log1` but includes merged branch logs, too.
  #
  # - Shows one log entry per line, formatted like:
  #
  #   * HASH AUTHOR DATE "HEAD -> my-branch"DESCRIPTION
  #   * HASH AUTHOR DATE DESCRIPTION
  #   * ...
  #   | * HASH AUTHOR DATE "merged-branch"DESCRIPTION
  #   | * HASH AUTHOR DATE DESCRIPTION
  #   | * ...
  #   |/
  #   * ...
  #
  # - Thanks to:
  #
  #   https://stackoverflow.com/questions/9437182/git-show-all-branches-but-not-stashes-in-log
  #
  # - HINT: The date is added to the output via the --pretty, not the --date.
  logs = \
    log --graph --abbrev-commit --date=local --decorate \
        --branches --remotes --tags --notes --oneline  \
        --pretty="%C(yellow)%h%x09%C(cyan)%<(12)%an%x09%C(blue)%>(24)%ad%C(auto)%x09%D%s"

  # -------

  # Every now and then I have a brain flatus.
  tig = !tig

  # -------

  child-of = "! f() { \
    git --no-pager log --reverse --ancestry-path --format='%H' ${1}..HEAD \
      | head -1; \
   }; f \"$@\""

  # -------

  ref = reflog --date=iso --no-decorate

  # -------

# #######################################################################
# ***                         Commit Aliases                          ***
# #######################################################################

# BWARE/2024-08-07: These commit aliases are now very opinionated:
# - They each use `-c core.editor=editor-vim-0-0-insert-minimal`
#   to use a minimal Vim editor, with some handy shortcuts
#   (like <Ctrl-S> to save and quit (:wq), so you can finish
#   your commit message quicker!).
#   - REFER: See the source for more details. / CXREF: On DepoXy at:
#     ~/.kit/git/git-smart/bin/editor-vim-0-0-insert-minimal.vimrc

[alias]
  # Simple git-commit shortcut.
  ci = -c core.editor=editor-vim-0-0-insert-minimal commit

  # Type message at prompt.
  cm = -c core.editor=editor-vim-0-0-insert-minimal commit --message

  # - Some other commit alias ruminations:
  #   - Stage modified and deleted files, but not new files:
  #       git commit -a/--all
  #   - Show diff of what's being committed at bottom of commit message editor sess:
  #       git commit -v/--verbose
  #   - Combine them both for a quickie add-all, review, compose, and commit:
  #       cia = commit -a -v

  # Use `git cv` to open your EDITOR to compose a commit message.
  #
  # - One goal I have in life is to stop composing commit messages
  #   at the terminal prompt, and to *always* use Vim (my EDITOR).
  #
  #   (lb): Used 40% of the time (type message at prompt).
  cv = -c core.editor=editor-vim-0-0-insert-minimal commit --verbose
  #
  # For parity with `git cim` and `git civ`.
  civ = -c core.editor=editor-vim-0-0-insert-minimal commit --verbose

  # ***

  # Use `cim` and `cin` to amend the last commit, even with unstaged work.

  # (lb): `commit --amend` the long way: --fixup + wip + rebase + pop1.

  # (lb): 2020-11-24: At least I can say I use `cim` and `cin` a lot.
  # - I first had `cin` aliased from `cia` (commit/ci + amend/a), but I
  #   feel like `cin` complements `cim` better, and I like the idea of
  #   c-in → commit-in → commit into last commit (and then cim is like
  #   cim → commit-into-message → commit into last commit & edit message). #pneumonics

  cim = -c core.editor=editor-vim-0-0-insert-minimal commit --amend

  # Like `git cim`, but leave staged changes staged.
  # https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L167-L168
  # (https://github.com/mgedmin/dotfiles is technically not licensed: No license file.)
  cim-only = -c core.editor=editor-vim-0-0-insert-minimal commit --amend --only -v

  # Amend the staged changes to the latest commit.
  # - BWARE: If you only `git mv foo bar`, then `git diff --cached --quiet`
  #   returns true (i.e., nothing staged?!). But `git diff --cached` still
  #   prints the files being renamed.
  #   - SAVVY: So don't use --quiet, but test output instead.
  # - Note with f() wrapper, additional args echoed, e.g.,
  #     $ git cin --allow-empty
  #     Nothing staged --allow-empty
  #   But using fcn wrapper, doesn't echo.
  cin = "! f() { \
    if [ -n \"$(git diff --cached)\" ]; then \
      git commit --amend --no-edit \"$@\"; \
    else \
      >&2 echo \"Nothing staged\"; \
    fi; \
  }; f"
  # - Note this other way to do the same:
  #     commit --amend --reuse-message=HEAD

  # Commit staged using same commit message as latest commit.
  ciagain = "! f() { \
    if [ -n \"$(git diff --cached)\" ]; then \
      git commit --message \"$(git log -1 --format=%B)\" \"$@\"; \
    else \
      >&2 echo \"Nothing staged\"; \
    fi; \
  }; f"

  # Use signed, empty first commit.
  # - Use case: If you only sign commits before pushing (because you
  #   rebase often before publishing, and signing is slow), ensure
  #   the first commit is signed. (If you don't sign the first commit
  #   now, you can always sign it later, but not as easily as signing
  #   it now.)
  # - Use case: In addition to -S[igning], we'll also --allow-empty,
  #   for those who like to use a meaningful message but no content
  #   for the first commit (which also makes it easy to fixup changes
  #   before your first push, without having to fiddle with the --root
  #   commit).
  # - SAVVY: Call `git cinit -m` or `git cinit -v`
  cinit = ciinit
  ciinit = commit --allow-empty -S

  # Here's a clever way to change the last commit's author, courtesy:
  #   https://github.com/jessfraz/dotfiles/blob/master/.gitconfig [MIT]
  # (although I added argument verification).
  # *Credit an author on the latest commit*
  # - SAVVY/2023-11-20: To make yourself the author of the last commit:
  #     git commit --amend --no-edit --author="$(git whoami)"
  credit = "! f() { \
    true \
    && [ -n \"$1\" ] \
    && [ -n \"$2\" ] \
    && git commit --amend --author \"$1 <$2>\" -C HEAD \
    || echo \"USAGE: git credit <name> <email>\"; \
  }; f"

  # *** Obscure or obtuse commit commands, why not!

  # Create a commit with a simple message -- ‰ -- Which I use to delimit
  # my charm or WIP commits, so I can group related commits and make it
  # easier to digest the tig display when I'm working with dozens of DEV
  # commits applied to whatever feature branch on which I'm hacking.
  # 2021-06-11 17:46: Some name ideas:
  #   git delim-commit, but tab completion conflicts with git del[ete*] commands;
  #   git hr-commit, but not super discoverable;
  #   git cihr, is more discoverage with `git ci<TAB>`...;
  #   or even `git cihrule`, because you're likely to tab-complete anyway.
  cihrule = commit --allow-empty -m ‰

  # 2021-06-11: A friend has a coworker that uses the commit message
  # convention, "{user}'s first commit", "{user}'s second commit", etc.
  # HAHAHA. So I send this improvement, just commit a random message.
  cirand = "! f() { \
    rand_msg=$( \
      curl -L -s http://whatthecommit.com/ | \
         grep -A 0 '<p>' | \
         tail -1 | \
         sed 's/<p>//' \
    ); \
    git commit -m \"$rand_msg\"; \
  }; f"

# #######################################################################
# ***                   Staging and Commit Aliases                    ***
# #######################################################################

[alias]
  st = status

  # -------

  ad = add -p
  # 2020-11-24: I didn't even remember `git ad` was here.
  # - Would I remember instead if it was `git ap`?
  ap = add -p
  # ADDitional noise.
  # - Ref:
  #   https://www.reddit.com/r/git/comments/6ecr4o/git_dad/
  #   https://icanhazdadjoke.com/api
  # - Bored?
  #   curl -H "Accept: application/json" "https://icanhazdadjoke.com/search?term=bar"
  dad = !curl '"https://icanhazdadjoke.com/"' && echo && git add
  rad = !echo '   (⌐■_■)' && git add

  # -------

  wip = ! \
    git add -A && \
    git commit --no-verify -m '"WIP"'

  # See: bin/git-wipit
  wippit = wipit

# #######################################################################
# ***                       Files List Aliases                        ***
# #######################################################################

[alias]
  ls = ls-files

  # Use `git ignored` to show --assume-unchanged files.
  # - Docs/Ref:
  #     -v: "Similar to -t, but use lowercase letters for files that
  #          are marked as assume unchanged (see git-update-index(1))."
  #     https://stackoverflow.com/questions/2363197/
  #       can-i-get-a-list-of-files-marked-assume-unchanged
  ignored = !git ls-files -v | grep '"^[[:lower:]]"'

  # From Marius Gedminas, a command to see files that are .gitignore'd,
  # but I have git-ignored showing --assume-unchanged files, so I guess
  # I'll call this git-excluded.
  #   https://github.com/mgedmin/dotfiles/blob/master/gitconfig
  # Note: This command shows every file. For a more concise report
  # that only shows excluded paths (and not the files therein), try:
  #   git status --ignored
  excluded = ls-files --others -i --exclude-standard

# #######################################################################
# ***                      Show File Alias(es)                        ***
# #######################################################################

[alias]
  # Fetches and shows file from specific commit/branch, e.g., the long way:
  #
  #   git show develop:path/to/file.js | view -c 'set ft=javascript' -
  #
  # or the short way:
  #
  #   git view develop:path/to/file.js
  #
  # Note the final `-` so that Vim knows to read from stdin.
  #
  # Note if you specify just the commit:path, this command will use the
  # file extension for the Vim 'filetype' (so that syntax highlighting
  # works); otherwise, you can specify the filetype as the second arg.
  view = "! f() { \
    local extension=\"$2\"; \
    if [ -z \"${extension}\" ]; then \
      extension=\"${1##*.}\"; \
    fi; \
    git show \"$1\" | \
      view -c \"set ft=${extension}\" -; \
  }; f"

# #######################################################################
# ***                          Diff Aliases                           ***
# #######################################################################

[alias]

  # Use `git dff` to run git-diff... or, better yet, add yourself a Bash
  # alias, becaues you'll probably use this command often.
  # - I git-diff fairly frequently, so I've added an even easier
  #   Bash alias to my user environment
  #     # <somewhere deep inside my .bashrc>
  #     alias dff='git diff'
  # - Note we don't use `git df`, because `df` is an historic *nix command,
  #   and we don't want to confuse the user.
  # HINT/2021-01-30: (lb): I use Bash `dff` alias I setup that does same.
  dff = !git diff \"$@\"
  # For parity with `git dcd`, this is the --no-pager equiv. of `git dff`.
  dfd = !git --no-pager diff \"$@\"

  # Use `git dcc` to show a diff of what's already been *staged* (which
  # is what you'd see at the bottom of a `git commit -v` edit session).
  # - Note that `dc` is the *nix calculator app, so we use `git dcc`.
  # HINT/2021-01-30: (lb): I use Bash `dcc` alias I setup that does same.
  dcc = !git diff --cached \"$@\"
  # This `dcd` is like `dc`, except doesn't page; it just dumps to the term.
  dcd = !git --no-pager diff --cached \"$@\"

  # Show "unreleased" changes, i.e., changes since the most recent release tag.
  # Inspired by: https://gist.github.com/sethvargo/d10a81f219f6469889269af2076b4d39
  # (sethvargo/{} is technically not licensed: No license info.)
  # See also (sans fetch): https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L123-L124
  unreleased = "!git fetch --tags && git diff $(git latest-version)"
  # *show commits after the last release*
  # Inspired by: https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L119-L121
  unreleased-short = !git shortlog $(git latest-version)..
  unreleased-log = !git log $(git latest-version)..

  # Show word differences on the same line.
  # 2021-05-30: We'll see if I find this useful or not: it might make lines
  # longer that I'd prefer, or maybe I'll find that I prefer to compare
  # word differences vertically (over 2 lines) rather than horizontally.
  dword = diff --word-diff --color-words

  # From: https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L126-L131
  # *show changelog since the last release*
  unreleased-changelog = !git diff $(git latest-version) -- $(git changelog-filename)
  # *git changelog-filename [name] -- get or set the filename of the changelog file
  #  (default: HISTORY.rst) / used by other aliases such as 'git unreleased-changelog'*
  changelog-filename = "!f() { git config alias.changelog.filename \"$@\" || echo HISTORY.rst; }; f"

  # From: https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L232-L235
  # *show me a diff of all the changes made on this branch (useful after git pr or git mr)*
  # *(I do not understand why diff needs the third dot and log absolutely cannot accept the third dot)*
  branch-diff = !git diff $(git main-branch)@{u}...
  branch-log = !git log $(git main-branch)@{u}..
  # From: https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L192-L194
  # *git main-branch [name] -- get or set the name of the default branch (usually ['release'])*
  main-branch = "!f() { git config alias.main-branch.name \"$@\" || echo release; }; f"

# #######################################################################
# ***                     Undo and Undodo Commits                     ***
# #######################################################################

[alias]

  # See `git undo` command at: bin/git-undo

  # -------

  # HINT: If you `rollback` or `undo` accidentally and need to recover,
  #       you can find the commit you blew away in the reflog. Just run:
  #
  #         git reflog
  #
  #       (Though if you just want to undo an undo, run `git undo-undo`.)

  # -------

  # Use `git rollback` to unwind the latest commit and unstage changes.
  #
  # - Equivalent to (or just similar?):
  #
  #     git undo && git reset HEAD *
  #
  # 2020-05-24: I find myself running rollback, but then
  #             adding `git l`, so combine the two!
  #
  #   This was:
  #
  #     rollback = reset --mixed @~1
  #
  #   But now includes a one-liner of the commit you land
  #   on after rolling back.
  #
  #   Use case: I have multiple WIPs and want to rollback
  #   to the latest keeper commit.
  #
  #     rollback = ! \
  #       git reset --mixed @~1 && \
  #       git --no-pager log -1 --pretty=oneline --abbrev-commit
  #
  # 2020-05-27: Getting lazy with age. Rename `pop1`.
  #
  #   Let's call it `git pop1`, as in "pop 1 commit"
  #   as opposed to `git rollback`
  #
  #   (I briefly considered `git rb` but fear such a
  #   short alias risks being typed quickly and ENTERed
  #   without second thought -- which I've done before
  #   with other commands, running not the one I meant
  #   to! -- so let's not wire this operation to too
  #   short of an alias. Using 'pop' and a number is
  #   still pretty short, at least typing 'pop' is very
  #   quick.

  # 2020-10-27: Let's keep the paradigm rolling, adding pop* 2-9.
  popn = "! f() { \
    pad2 () { sed 's/^/  /'; }; \
    \
    if [ $1 -gt 1 ]; then \
      echo; \
      echo '  git reflog'; \
      echo '  ——————————'; \
      git quip -g | pad2; \
    else \
      echo; \
      echo '  pop commit'; \
      echo '  ——————————'; \
      git --no-pager log -1 --decorate --color=always | pad2; \
      echo; \
      echo \"  If you want a do-over:\"; \
      echo \"    git ci -m \\\"$(git --no-pager log -1 --format=%s)\\\"\"; \
    fi; \
    \
    echo; \
    echo '  git reset --mixed @~'$1; \
    echo '  —————————————————————'; \
    git reset --mixed @~${1} | pad2; \
    \
    echo; \
    echo '  new HEAD'; \
    echo '  ————————'; \
    git quip | pad2; \
  }; f"
  pop1 = "! git popn 1"
  pop2 = "! git popn 2"
  pop3 = "! git popn 3"
  pop4 = "! git popn 4"
  pop5 = "! git popn 5"
  pop6 = "! git popn 6"
  pop7 = "! git popn 7"
  pop8 = "! git popn 8"
  pop9 = "! git popn 9"

  # Note that, used in a pipe (output not going to terminal), Git doesn't
  # "decorate" ref names (e.g., it would print "commit abcd1234", instead
  # of "commit abcd1234 (HEAD -> main)". So always --decorate.
  # - REFER: log.decorate in `man git-log`.
  quip = ! git --no-pager log -1 --pretty=oneline --abbrev-commit --decorate --color=always

  # -------

  # Use `git undo` to undo the latest commit, but not to unstage.
  #
  # - The undo command is in its own file on PATH, so
  #   that it runs, not git-extras' /usr/bin/git-undo.
  #
  #   See:                CXREF: For DepoXy devs:
  #
  #     bin/git-undo        ~/.kit/git/git-smart/bin/git-undo
  #
  # - This is useful if you want to rewrite the commit message,
  #   or if you want to incorporate changes without having to
  #   perform a squash operation.
  #
  # - NOTE: The git-extras package installs its own /usr/bin/git-undo,
  #         which shadows any alias defined here, in the .gitconfig.
  #
  #   - So while this operation could be an alias because it's so simple,
  #     it instead must be a file found (first) on PATH.
  #
  # - The operation is very simple. It's essentially:
  #
  #     undo = reset --soft @~1

  # -------

  # Use `git undo-undo` to undo an undo, duh!
  # - The undo-undo command undoes a --soft reset.
  undo-undo = reset 'HEAD@{1}'

# #######################################################################
# ***                 Checkout Fetch Push Pull Rebase                 ***
# #######################################################################

[alias]
  # Use `git co` instead of `git checkout` because the latter is too much typing.
  # - Note that git-checkout completion includes remote branch names in
  #   completion, which could be annoying, especially if there are lots
  #   of remote branches, and if your convention is to prefix the upstream
  #   remote name, anyway. (E.g., I always checkout a remote branch using
  #   the command `git co -b some-branch upstream/some-branch`, and would
  #   never use the shorthand, `git co some-branch`.)
  #   - Consider using a Bash environment setting to disable this behavior:
  #       GIT_COMPLETION_CHECKOUT_NO_GUESS=1
  #   - You can also run `git co --no-guess` (or `git switch --no-guess`),
  #     but that option is not honored via aliasing. (So if you want to
  #     always disable this behavior for this alias, you must use the
  #     Bash environment approach.)
  co = checkout

  # DATED/2022-10-05: I don't use either 'origin' nor 'upstream' remote names
  # any more, and I don't want them relied upon herein. git-smart centers
  # around a lot of the author's conventions, and I no longer use these.
  #   # Use `git po` to push to the most commonly pushed remote (probably), "origin".
  #   po = push origin HEAD
  #   # And use `git pu` to push to another commonly used remote name, "upstream".
  #   pu = push upstream HEAD

  # 2020-06-18: (lb): My latest workflow adopts the remote names "proving"
  # and "release" instead of "origin" and "upstream".
  # CXREF: mega-comment in my git-my-merge-status project for why the innovation.
  pp = push proving HEAD
  # 2022-10-05: (lb): Refuse to push 'liminal' branches to 'release' upstream.
  # - This is my convention: I use so-called 'liminal' branches to demo changes,
  #   or to ensure they're backed up, but with the caveat that I'll rebase those
  #   changes eventually. So I don't want anyone building from those changes!
  #   - Basically, pushing `liminal` to my personal repo (where I've got my
  #     forks of projects) is fine, but I don't want to push `liminal` branches
  #     to the release repo.
  # - Also, the 'release' upstream shouldn't have any cruft.
  #   - It seems like 'release' and 'develop' branches are sufficient.
  # - So rather than push any-old branch:
  #     pr = push release HEAD
  #   We'll check the current branch and adjust accordingly.
  # - (Alternatively, we could make `git pr` on push the 'release' branch, e.g.,:
  #     local current_br=\"$(git main-branch)\"; \
  #    but then `git pr` works different from `git pp`, so maybe let's not.)
  # git-pr: Push to 'release' remote, but reject unconventional branches thereunto.
  pr = "! f() { \
    local current_br=\"$(git rev-parse --abbrev-ref=loose HEAD)\"; \
    if [ \"${current_br}\" = \"release\" ] || [ \"${current_br}\" = \"develop\" ]; then \
      git push release HEAD; \
    else \
      >&2 echo \"ERROR: \\`git pr\\` is restricted to branches named 'release' and 'develop'.\"; \
    fi; \
  }; f"

  # -------

  # Use `git re` to show the URL of each remote after its name.
  # 2020-03-11: Check out the new `bin/git-re` tidy remote reporter!
  # - LATER: Remove this alias. For now, telling YOU where to look.
  #  re = remote -v
  r = re

  # -------

  # Run `git sup` periodically (or maybe after every git-pull) to process
  # any changes to the project submodules).
  sup = submodule update --init --remote

  # -------

  # 2021-02-01: Only took 10+ years to figure this one out! (And now I can
  # stop running `git fetch {upstream} && git rebase {upstream}/{branch}`!)
  #
  # - Note other aliases also defined by git-smart (or by my private cfg)
  #   that risk being confused with this alias (e.g., they have similar
  #   initials, `push release` → `pr`, just like `pull --rebase` → `pr`):
  #
  #     pr = push release HEAD
  #     pur = push -u release HEAD
  #
  #   Hopefully I can keep these straight... should be easy, the pull
  #   command is run without specifying a remote or branch, so it makes
  #   sense it can be the one one-character alias that starts with 'p'.
  #
  # 2021-02-01: Oh, HAHA, and here I thought I was being clever! Turns out
  # I added a `git up` alias as early as 2016, which is better that what I
  # was originally thinking for `git p`:
  #
  #     p = pull --rebase
  #
  # So let's rename `up` instead, and hopefully now I'll remember it's here!
  #
  # HISTORY: This alias was named `git up`, but I long ago forgot it existed.
  # That, or I didn't realize its advantage. Which is greatly. So let's shorten
  # it to just 'p'. This also helps with mnemonics, as 'pull' starts with 'p',
  # whereas 'up' has no obvious connection (unless you think of reversing the
  # first two characters in 'pull'; or maybe it was meant for you to think that
  # you were incorporating changes from upstream? In any case, confusion gone).
  #
  # USAGE: Use `git p` to stash changes, pull, rebase, and pop the stash.
  #
  # - Benefit (IMO): Runs rebase, and not merge, like pull does by default.
  #   (Specifically, I never merge feature work; only rebase.) Also stashes.
  #
  p = pull --rebase --autostash

  # See also related option:
  #
  #   git config --global branch.autosetuprebase always
  #
  # which configures each new branch to automatically run rebase on
  # pull, rather than merge. (But I still like the `git p` alias.)

  # -------

  pff = pull --ff-only
  puff = pull --ff-only

  # -------

  # Use `git bump` to quickly run a common rebase operation.
  # - Without arguments, checks out the 'develop' branch, fetches from
  #   the 'upstream' remote; and rebases 'develop' atop 'upstream/develop'.
  # - You can specify the following optional arguments:
  #     git bump <local-branch> <upstream-remote> <upstream-branch> <local-remote>
  # - The command is essentially:
  #     git checkout 'develop'  # or the named branch ($1)
  #     git fetch 'upstream'  # or the named remote ($2)
  #     git rebase upstream/develop  # or the named upstream branch ($2/$3)
  # - git-bump is inherently aliased because found on PATH.
  #    bump = !${GITSMART_BIN:-${HOME}/.local/bin}/git-bump \"$@\"

  # Use `git fam` to fetch from both the 'origin' and 'upstream' remotes,
  # and to remove from the local branches list those branches deleted
  # from each of the two remotes.
  # (lb): See comments atop this file re: How branches are named.
  # - Former workflow: 'origin' and 'upstream'.
  fam = fetch --multiple origin upstream --prune
  # - Latest workflow: 'proving' and 'release'.
  fpr = fetch --multiple proving release --prune

  # Use `git fap` to fetch and prune branches deleted from each of the remotes.
  # - (lb): `--all` fails if any remote cannot be reached, which affects me
  #         particularly because every repo I've got tracks a backup repo on
  #         an offline storage device, which is rarely online. Meaning, --all
  #         almost --all'ways fails for me. Additionally, `--all` can take a
  #         while if there are many remotes.
  #         - As such, oftentimes it's better to be deliberate when fetching
  #         from remotes -- that is, consider using either of the commands
  #         `fam` or `fpr`, but not `fap`.
  # - (lb): Or perhaps we just ignore errors, eh.
  #   - Original call:
  #       fap = fetch --all --prune
  #   - We could instead just toss stderr:
  #       fap = "!f() { git fetch --all --prune 2> /dev/null; }; f"
  #   - Or better yet fetch in same order as git-re prints remotes,
  #     and indicate if success status of each fetch:
  fap = re fetch --prune

  # Use `git pup` to push a branch and add tracking information (e.g., to
  # be used on a later `git pull`, or for `git status` to tell you things).
  # - I tried `git pu` for a spell, but it didn't stick, e.g.,
  #     pu = push -u origin HEAD
  #   which I think is because 'pu' is not as snappy as 'pup'.
  #   Mnemonically speaking, remember that you want to set the
  #   UPstream tracking information on Push, so it's called PUP.
  # - See also the more direct call to set just the tracking branch, e.g.,
  #     git branch -u <remote>/<branch>
  # 2020-07-01: I never use this command. Let's disable it.
  # - (I'll instead use, e.g., `git pp -u`, if I have to.)
  #  pup = push --set-upstream origin HEAD

# ***

# 2021-02-01: See recently added `git p` alias (--rebase --autostash).
# - Because I *only* rebase (I don't like merge commits) this setting
#   ensures that pull fails unless if it can --ff-only.

[pull]
  ff = only

# #######################################################################
# ***              Redoing Commits and Rewriting History              ***
# #######################################################################

[alias]
  # Show rebase recipe with '--fixup' commits ordered
  # and commanded to 'f'ixup.
  # - This opens the rebase-todo in your EDITOR, unless you've
  #   installed interactive-rebase-tool and set `sequence.editor`.
  #   - CXREF: Interactive rebase tool:
  #       https://github.com/MitMaro/git-interactive-rebase-tool
  #   - CXREF: Check out DepoXy development environment orchestrator
  #     to see how it installs and wires interactive-rebase-tool.
  #       https://github.com/DepoXy/depoxy#🍯
  #     If you've installed DepoXy, the config is likely at:
  #       ~/.depoxy/ambers/home/.gitconfig.local
  ria = rebase -i --autosquash

  # The git-ria! command shows a much less noisy todo (with comments removed).
  # And DepoXy's git-ria calls interactive-rebase-tool (shadows previous alias).
  # So this command exists for DepoXy users who want to see unadultered todo.
  # - If you want the `append_todo_help` reminders back, use this.
  ria-helpful = -c sequence.editor="${EDITOR}" rebase -i --autosquash

  # - From man git-rebase:
  #
  #     --no-verify
  #         This option bypasses the pre-rebase hook. See also githooks(5).
  ria-no-verify = rebase -i --autosquash --no-verify

  # - Use case: Works well with `git ci --fixup=<>`, e.g.,
  #
  #     git ci --fixup=abcd1234 && git ria abcd1234^
  #
  # - Common workflow:
  #
  #   - While working on a new feature, I make a small change
  #     that should be part of a previous commit.
  #
  #   - Run `st` (git status) to see the file path, and copy it.
  #
  #   - Run `gitk -- <file> &` and find and copy appropriate commit hash.
  #
  #     - Or better yet find it with `git latest <search terms>`
  #       and then verify using `tig`, which has replaced gitk in my D2D.
  #
  #   - Run `git add -p <file>`, and then `git ci --fixup=<hash>`.
  #
  #   - Run `git wip` to commit other uncommitted changes.
  #
  #   - Run `git ria <hash>^` to fixup the small change to the past commit.
  #
  #   - Save and close the rebase script.
  #
  #   - Run `git pop1` to rollback the WIP commit.

  # If the rebase pauses and you need to resolve a conflict,
  # here's a shortcut to continue the rebase quickly.
  #
  # - Noice! I almost never care about editing message during rebase, as
  #   I'm usually just resolving conflicts, or I already ran --amend.
  #
  #   - GIT_EDITOR=true courtesy:
  #
  #       https://stackoverflow.com/questions/43489971/
  #         how-to-suppress-the-editor-for-git-rebase-continue
  #
  # Previous iterations of this/these commands:
  #
  #  rc = !GIT_EDITOR=true git rebase --continue
  #
  #  # Git cherry-pick --continue.
  #  #     ░      ▒      ▓
  #  cpc = cherry-pick --continue
  #
  # Note that rebase uses both git-rebase-todo and MERGE_HEAD, so
  # check the former first, to distinguish from merge.
  rc = "!f() { \
    if [ -f .git/rebase-merge/git-rebase-todo ]; then \
      GIT_EDITOR=true git rebase --continue; \
    elif [ -f .git/CHERRY_PICK_HEAD ]; then \
      GIT_EDITOR=true git cherry-pick --continue; \
    elif [ -f .git/MERGE_HEAD ]; then \
      GIT_EDITOR=true git merge --continue; \
    fi; \
  }; f"

  cancel = ! git abort

  # Automatic conflict resolution.
  # From: https://gist.github.com/pksunkara/988716#file-config-L263-L264
  ours = "!f() { git checkout --ours $@ && git add $@; }; f"
  theirs = "!f() { git checkout --theirs $@ && git add $@; }; f"

  # ***

  # I've always wondered why `cherry-pick` and not just `pick`, or both,
  # considering users use `pick` in the sequence editor todo.
  pick = cherry-pick

  # ***

  # SAVVY: ``4b825dc...`` is the hash of the empty tree::
  #
  #   $ git hash-object -wt tree --stdin < /dev/null
  #   4b825dc642cb6eb9a060e54bf8d69288fbee4904
  #
  #   $ git hash-object -t tree /dev/null
  #   4b825dc642cb6eb9a060e54bf8d69288fbee4904
  #
  #   $ git mktree </dev/null
  #   4b825dc642cb6eb9a060e54bf8d69288fbee4904
  #
  # - REFER: https://stackoverflow.com/questions/9765453/
  #   is-gits-semi-secret-empty-tree-object-reliable-and-why-is-there-not-a-symbolic

  # USAGE: `git insert-empty-first-commit <commit-message>`
  # REFER: https://stackoverflow.com/questions/645450/insert-a-commit-before-the-root-commit-in-git
  insert-empty-first-commit = "!f() { \
    local tree=$(git hash-object -wt tree --stdin < /dev/null); \
    local commit=$(git commit-tree -m \"${1:-welcome to the machine\"} ${tree}); \
    git rebase --root --onto ${commit}; \
  }; f"

  # ***

# #######################################################################
# ***                    Miscellaneous Git Aliases                    ***
# #######################################################################

[alias]
  # Empirically speaking.
  #  whoami = config user.email
  # These are similar:
  whoami = "! printf '%s <%s>\n' \"$(git config user.name)\" \"$(git config user.email)\""
  # To include the name, from https://github.com/mgedmin/dotfiles/blob/master/gitconfig:
  #  whoami = var GIT_COMMITTER_IDENT
  #  whoami = !git var GIT_COMMITTER_IDENT | sed 's/ [0-9]\\+ [-+0-9]\\+$//'
  # Or even, from https://gist.github.com/pksunkara/988716#file-config-L257
  # the author of the last commit :
  #  # whoami2 = !sh -c 'git --no-pager log -i -1 --author=\"$1\" --pretty=\"format:%an <%ae>%n\"' -
  #  whoami2 = !sh -c 'git --no-pager log -i -1 --pretty=\"format:%an <%ae>%n\"' -
  whose-commit = "!f() { \
    git --no-pager log -i -1 --pretty=\"format:%an <%ae>%n\" \"$@\"; \
  }; f"

  # SHA of the very first commit.
  first-commit = rev-list --max-parents=0 HEAD

  # Where `git nth-commit 1` is same as `git first-commit`.
  # And where `git nth-commit <number-bigger-than---count>`
  # prints latest commit (HEAD) sha.
  nth-commit = "!f () { \
    local dist_from_head=$(git rev-list HEAD --count); \
    dist_from_head=$((dist_from_head - ${1:-1})); \
    git log --skip=${dist_from_head} --max-count=1 --pretty=format:%H | cat; \
  }; f"

  # https://github.com/mgedmin/dotfiles/blob/1da8d86/gitconfig#L243-L244
  # *show current commit SHA; try also*:
  #   git sha --short
  #   git sha [--short] somebranch
  sha = "!f() { \
    rev=HEAD; \
    for a; do \
      case \"$a\" in \
        -*) ;; \
        *) rev=;; \
      esac; \
    done; \
    git rev-parse \"$@\" $rev; \
  }; f"

  # 2022-12-10 17:22: See also sha, forgot about that one.
  id = rev-parse --short=11

# #######################################################################
# ***                 Set your own Default Branch Name                ***
# #######################################################################

[init]
  # New to Git v2.28 (2020-07-26), there is an easier way to set the default
  # branch name: Use init.defaultBranch, rather than copying from a template.
  # - Here I'll show how to do both. Because templateDir is still interesting.
  # - Obviously, your preferred default branch name likely differs from mine!
  # - Note that you can enable both, but templateDir will beat defaultBranch.
  #
  # Use a default branch name other than Git's ahistoric default.
  defaultBranch = release
  #
  # If you're not running Git v2.28 yet and would like to change the default
  # branch name, uncomment the following, and be sure to install the template
  # from this repo to your user's config directory. When you run `git init`,
  # the template directory contents will be copied to the new working tree's
  # .git/ directory.
  # - You might also want to use the templateDir to ensure that the same
  #   hooks are always setup on git-init, or even an info/exclude file.
  # - For some examples setting up hooks using the template, refer to:
  #     https://git-template.readthedocs.io/en/latest/
  # - The template directory is pretty basic if you just want to set the
  #   default branch name. E.g.,
  #     $ cat ~/.config/git/template/HEAD
  #     ref: refs/heads/release
  #
  #  templateDir = ~/.config/git/template/

# #######################################################################
# ***                  Your Private .gitconfig.local                  ***
# #######################################################################

# YOU/DEV: Put your [user] and other private config in a separate file
#          named '.gitconfig.local' that's located (symlinked) alongside
#          this file (in the same directory).

# NOTE: Include last, so local aliases override those above.

[include]

  path = .gitconfig.local