= Dotfiles
:link-devtools: https://github.com/kieranpotts/devtools :link-bootstrap: https://github.com/kieranpotts/bootstrap :link-gitscm: https://git-scm.com/ :link-gitforwindows: https://gitforwindows.org/ :link-gitlfs-install: https://github.com/git-lfs/git-lfs/blob/main/INSTALLING.md :link-gitlfs-migrate: https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.adoc :link-github-lfs: link:https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github :link-codespace-settings: https://github.com/settings/codespaces :link-gitignore: https://git-scm.com/docs/gitignore :link-ohmyposh: https://ohmyposh.dev/
These are my personal Unix dotfiles. They include:
git sync, git amend,
git squash, git fixup, git undo.These dotfiles complement my {link-devtools}[devtools] – additional tools and configuration for use directly on Windows.
== Documentation
=== Requirements
These dotfiles are intended for use in Bash on Debian-based systems, but I've made some effort to make them as cross-platform compatible as possible. Most of the shell scripts are POSIX-compliant and will therefore run in all Unix shells. They can be used on Windows too, via a Linux emulator like {link-gitforwindows}[Git Bash for] or a virtual machine like WSL.
TIP: On Debian systems, my {link-bootstrap}[bootstrap scripts] can be used to install all dependencies, so automating the following steps. For Git Bash on Windows, my {link-devtools}[devtools] repository bundles most of the required programs, but some of the below steps still need to be done manually.
==== REQUIRED programs
The only REQUIRED program is Git. The Git configuration has been tested with {link-gitscm}[Git] v2.39.1 and is expected to be compatible with versions after 2.35. For Debian distros, run the following command to check which is the current version of Git available via the APT package manager.
If the available version is ≥ v2.35, go ahead and install from the default package registry.
If you want to install a newer version of Git than is available via the
package registry, use wget to download the source of the desired version.
For example, to download the source for Git v2.35.0, run the following command.
Before extracting the files from the archive, install the following packages.
Extract the source files for the Git package, then navigate to the extracted directory.
Run the following command to build and install the Git package. This is a slow operation.
Restart your terminal, then check the installed Git version with the command
git --version. Use rm to clean-up the temporary files and directories
created in this process.
==== OPTIONAL programs
It is RECOMMENDED to install Git Large File Storage (LFS). This is a Git extension that removes large files from Git repositories and stores them elsewhere, cross-referenced from the Git repositories using pointers. Git LFS is included in the distribution of {link-gitforwindows}[Git for Windows], while {link-gitlfs-install}[packages are available for popular Linux distributions]. Once installed, run the following command to set up Git LFS globally in your local Git instance:
In each Git repository where you want to use Git LFS, run the following command
to configure the file types that you'd like Git LFS to manage. Alternatively,
you can edit the .gitattributes file directly (changes to this file MUST
be committed).
Then commit and push as normal. To convert existing files previously committed
to the repository use the git lfs migrate command. See the
{link-gitlfs-migrate}[Git LFS documentation] for further instructions, and more
{link-github-lfs}[about large files on GitHub].
Besides Git LFS, the following programs are also OPTIONAL:
My dotfiles include configurations for LazyGit and Neovim, while Delta and Oh-My-Posh may be used to enhance Git and the terminal prompt, respectively. For Debian systems, you can use my {link-bootstrap}[bootstrap scripts] to install these programs, or follow the instructions from the links above to install manually. For Git Bash on Windows, most of these programs are bundled with my {link-devtools}[devtools] – except for Neovim, which is not available as a standalone binary.
=== Installation
To install these dotfiles, fork-and-clone the upstream repository to any location on your local machine, then follow the steps below. This process needs to be repeated for each environment – so, once for WSL and once for Git Bash, if using both on the same Windows machine.
==== 1. Run the ./install.sh script
Change to the root directory of the cloned repository and run the
./install.sh shell script.
IMPORTANT: For Git Bash on Windows, run the terminal program as administrator.
The first time you run this, you will need to exit your terminal program then restart it. Doing so will create a new login shell, which will load the newly-installed dotfiles at startup.
The install.sh script can be safely run multiple times, and it is RECOMMENDED
to re-run it whenever you git pull the latest changes from the upstream
dotfiles repository, so that any new symlinks are created as required.
==== 2. Add the bin/* directories to your system PATH environment variable
This repository's bin directory contains various git-* shell scripts that
are mapped to Git aliases. It is RECOMMENDED you add the bin directory to
your system PATH environment variable, to make these Git commands available
from the command line. For Bash, this is done automatically via configuration
in the global .bashrc file. To make the Git aliases available in the Git
Bash emulator on Window, you will need to manually update Windows' PATH
environment variable.
==== 3. Create symlinks to the configuration files
Configuration files are included for various command line development tools.
To use these configurations, symlinks must be created to them from the
filesystem locations the programs expect them to be. The ./install.sh
script does this automatically for non-Windows environments. To use the
LazyGit, Neovim and tmux configurations in Git Bash for Windows, run Windows
Powershell in administrator mode and execute the following commands, changing
the filesystem paths as required.
New-Item -ItemType SymbolicLink -Path "C:\Users\[User]\AppData\Roaming\lazygit\config.yml"
-Target "C:\path\to\dotfiles\etc\lazygit\config.yml" `
-Force
New-Item -ItemType SymbolicLink -Path "C:\Users\[User]\AppData\Local\nvim\init.vim"
-Target "C:\path\to\dotfiles\etc\nvim\init.vim" `
-Force
-Path "C:\Users\[User]\.tmux.conf"
-Target "C:\path\to\dotfiles\etc\tmux\tmux.conf" -Force New-Item -ItemType SymbolicLink
-Path "C:\Users[User].tmux\dev" -Target "C:\path\to\dotfiles\etc\tmux\inc\dev"
-Force==== 4. GitHub Codespaces configuration
The ./install.sh script can be used to bootstrap your GitHub Codespaces
environments, too. Only a subset of the dotfiles configuration are enabled
in Codespaces – limited only to Bash aliases and functions at this time. Go
to your {link-codespace-settings}[GitHub Codespaces options] and enable the
following setting.
image::./_/github-automatically-install-dotfiles.png[]
=== Configuration
The ./install.sh script will have established various symlinks in your home
directory for the Unix dotfiles. For example, ~/.gitconfig will be symlinked
to /path/to/dotfiles/dist/global.gitconfig.
IMPORTANT: You SHOULD NOT change the dotfiles symlinks (eg. ~/.gitconfig) or
edit the contents of their target files in this repository's dist directory.
Instead, you can make changes to your dotfiles configuration via the "local"
files that have been added to your home directory – as explained below.
The following files will be added to your home directory.
~/local.profile~/local.bash_profile~/local.bashrc~/local.gitconfig~/local.gitignore~/local.gitmessageThese are not symlinked and they are not kept under version control, either. Therefore, you can safely edit these files to make configuration changes in each individual environment in which you have installed these dotfiles. It's via these "local" files that you extend the "global" dotfiles configurations shared via this repository.
Whenever you make changes to any of the "local" shell startup scripts –
~/local.bashrc, ~/local.bash_profile, or ~/local.profile – you can call
the reload! function to re-source the shell startup scripts, so your changes
take effect immediately without needing to restart the shell session.
=====
If you already had files like .profile or .gitconfig in your user directory,
the ./install.sh script will have created backups of these files before
replacing them. The backup files will be named with the "backup" prefix. For
example, your existing ~/.bashrc file will have been renamed
~/backup.bashrc. You may need to manually copy-and-paste existing
configurations from the old "backup" files to the new "local" files.
==== Git configuration
You MUST edit the ~/local.gitconfig file to configure your Git user profile
information. This data will be embedded in commit objects:
When you ran the ./install.sh script, your previous Git configuration would
have been backed up to ~/backup.gitconfig. You SHOULD review the contents of
this file and copy any other configuration you wish to keep to the new
~/local.gitconfig file.
NOTE: From now on you SHOULD NOT use the git config --global command to
update your Git configuration. If you do, this command will update the file
symlinked from ~/.gitconfig. To avoid this, you SHOULD instead directly edit
the ~/local.gitconfig file.
You MAY also edit the ~/local.gitignore file to configure global
{link-gitignore}[Git ignore rules]. By default, this file adds rules to ignore
files or directories named \__TODO__, \__NOTES__ or \__SCRIPTS__ in any
Git repository anywhere on your local filesystem. It means the contents of
these paths will be private to you and will not be committed to source control.
==== Prompt themes
A couple of different solutions for customizing the command line prompt are included with these dotfiles.
The first solution depends on {link-ohmyposh}[Oh-My-Posh], a cross-platform
prompt theming framework. It means the prompt theme can be used in Powershell,
Git Bash, WSL, and other shells. The theme is enabled via the following command
in the ~/local.bashrc file. You just need to uncomment the line to enable it.
Then either restart the terminal or call the reload! function to re-source
the shell startup scripts.
Alternatively, you can enable the git-prompt.sh or git-prompt-simple.sh
scripts, both of which add Git repo information to the standard prompt line.
Uncomment the following lines in the ~/local.bashrc file, instead.
source ~/.prompt-themes/git-prompt.sh export PS1='[\033[01;32m]\u@\h[\033[00m]:[\033[01;34m]\w[\033[01;31m]$(__git_ps1)[\033[00m]\$ ' GIT_PS1_SHOWDIRTYSTATE=1 GIT_PS1_SHOWUPSTREAM="auto" GIT_PS1_UPSTREAMEQUALS=""
=== Usage
==== Shell environment variables
The following environment variables are enabled.
[cols="1,1,1"] |=== |Name |Description |Shells
|X_GIT_COMMIT_VERIFY=1
|Change to 0 to apply --no-verify flag to git commit operations done via the Git aliases.
|Bash
|===
In addition, in Bash the PATH environment variable is extended to include
$HOME/bin and /path/to/dotfiles/bin, if those directories exist.
==== Shell aliases
The following shell aliases are enabled.
[cols="1,2,3,1"] |=== |Alias |Command |Description |Compatibility
|..
|cd ..
|Change up one directory.
|POSIX
|\...
|cd ../..
|Change up two directories.
|POSIX
|\....
|ch ../../..
|Change up three directories.
|POSIX
|\.....
|cd ../../../..
|Change up four directories.
|POSIX
|egrep
|egrep --color=auto
|Enable colorized output by default.
|POSIX
|fgrep
|fgrep --color=auto
|Enable colorized output by default.
|POSIX
|g
|git
|Shortcut for the oft-typed git command.
|POSIX
|grep
|grep --color=auto
|Enable colorized output by default.
|POSIX
|l
|ls -laF --color
|List all files (including hidden ones) in long-form.
|POSIX
|ld
|ls -laF --color \| grep --color=never '^d'
|List only directories.
|POSIX
|lf
|ls -laF --color \| grep --color=never '^-'
|List only files.
|POSIX
|ls
|ls --color
|Enable colorized output by default.
|POSIX
|mkdir
|mkdir -p
|Make directories recursively by default.
|POSIX
|reload!
|. ~/.bashrc
|Reload the Bash shell startup scripts.
|Bash
|s
|sudo
|Shortcut for sudo ("superuser do").
|POSIX
|===
==== Shell functions
The following shell functions are enabled.
[cols="1,3,1"] |=== |Function |Description |Compatibility
|buildDockerImage ([name_for_created_image])
|Build a Docker image from a Dockerfile in the current directory.
|POSIX
|runDockerContainer [image_name]
|Run a Docker container from an image.
|POSIX
|runDockerFromFile ([name_for_created_image])
|Build an image and immediately run a container in the background from it.
|POSIX
|listDockerImages
|List all available docker images.
|POSIX
|sshDockerContainer [container_id]
|SSH into a running container.
|POSIX
|===
==== Git config
The .gitconfig file modifies Git's default behavior in the following ways:
git merge always records explicit merge commits (ie --no-ff is the
default).
git fetch automatically prunes refs to non-existent upstream branches
and deletes non-existent tags.
git pull rebases by default.
--autosquash rules are automatically applied on rebase operations.
git push pushes new tags, as well as new commits.
Upstream branches are tracked automatically, and tracked branches are constrained to have the same names.
Opts-out of security checks for Git repositories on external storage
devices (safe.directory).
==== Git aliases
50+ Git aliases are included with these dotfiles. These extend Git's built-in
operations, providing shortcuts for common Git workflows. All the Git aliases
are implemented as shell scripts in the bin directory. For the aliases to
work, the bin directory MUST be added to your system path.
To see what aliases are available, run the command git aliases – itself
an alias! – in your terminal.
WARNING: Some of the operations enabled via the Git aliases are potentially destructive. For example, some Git aliases rewrite commit histories.
''''
Copyright © 2020-present Kieran Potts, link:./LICENSE.txt[MIT license]
Third-party components: These dotfiles integrate the following third-party components:
Acknowledgments: For the custom scripts and configuration, inspiration has been taken – and, in some cases, code shamelessly copied – from some of these related projects: