[TOC]

Installation

Obviously, you first need to have GNU Stow installed.

Then it is a simple matter of pulling the dotfiles repository:

git clone https://gitlab.com/hook/dotfiles.git ~/dotfiles
cd ~/dotfiles
git submodule init
git submodule update
stow fish vim tmux # plus/minus whatever else you like

With which you:

1. check out the latest version of these dotfiles’ Git repository into your ~/dotfiles directory (feel free to change it to ~/.dotfiles, if you prefer),
2. change into the ~/dotfiles directory, so Stow is in the right directory relative to the configuration files and folders we want to populate,
3. initialise and update the submodules (e.g. ranger_devicons)
4. using stow to create the the links to the right configuration files (in the right directories) – in the above example that would be the contents of the ~/dotfiles/fish, ~/dotfiles/vim and ~/dotfiles/tmux. Substitute that for the folders that you are actually interested in.

For dependencies for any individual dotfiles see the Dependencies section below.

Update

You can later update the dotfiles (e.g. for Vim) to sync them with this repository by running:

cd ~/dotfiles
git pull
git submodule update
stow --restow vim

Remove

If you do not want to use a specific dotfile directory any more (e.g. Fluxbox), do:

cd ~/dotfiles
stow --delete fluxbox

Usage

Convert Scanned PNGs to PDF

convert-scanned-pngs-to-pdf takes a list of .png files and reduces their size, converts them to JPEG and stores them in a PDF. Useful, when you scan long documents (and cannot be arsed to change the scanner settings).

(Glob is very useful here.)

Git

I decided to store my Git (and Delta) config in Stow too. Any authentication or other user/computer-specific configurations should go into ~/.config/git/user, which is explicitly ignored by this repository.

Glob

Since globbing for letters (alphabet characters) is not implemented yet in Fish Shell, with ample help of Fabian Boehm (fabo), I am using the glob function to mitigate this shortcoming.

glob is essentially just a wrapper for find, so it will output any file or folder it finds with the argument you give it. It uses an optional flag --case-insensitive / -i, which, as the name implies, makes the search case-insensitive.

For example running the following in dotfiles/fish/.config/fish/functions:

glob '[a-c,e]*'

will result in:

./bass.fish
./cascade_kwin.fish
./cpb.fish
./eza.fish
./convert-scanned-pngs-to-pdf.fish

Not very useful by itself, but if you wrap it in brackets, it can replace the aforementioned current shortcoming of Fish.

So, where you would expect git add [a-c,e]* to work, instead, you pass the glob through glob first, like this:

git add (glob '[a-c,e]*')

Hyprland

A fairly simple Hyprland set-up, really. See dependencies for more info.

To make it all work well, it is best to pull Dunst and Waybar settings at the same time:

stow hypr dunst waybar

Since Kitty is set up as the default terminal emulator, setting it up is a good idea too:

stow kitty

The most important keybindings are (Super = "Windows" key; also note that the keyboard layout is set to Neo2!):

• Control + F1-F9 = select tag / virtual desktop
• Control + Shift + F1-F9 = move window to tag / virtual desktop
• Super + L = lock screen
• Super + Enter = open terminal window
• Alt + F4 = kill/close window
• Alt + Space – open launcher
• Control + Q = quit Hyprland
• Super + V = (un)float window
• Super + J = toggle window split between vertical and horizontal
• Super + S = toggle special workspace / "skratchpad"
• Super + Shift + S = move window to special workspace / "skratchpad"

Another important change is that, it puts external monitors to the left of the built-in laptop monitor, since that is my usual physical set-up. And when closing and opening the laptop lid, the built-in monitor will turn off/on.

i3

The biggest change is that I use the Meta (Win) key as the modifier for switching between virtual desktops/tags and all similar window-related tasks.

Apart from that there are typical keybindings for screen locking, volume and screen brightness.

Make sure to stow i3 dunst to also have the launcher ready.

Tmux

Most changes make the keybindings closer to GNU Screen (e.g. Ctrl+A instead of the default Ctrl+B) and Vim.

Most other changes are just small visual niceties, plus the small mem-cpu-load monitor in the corner.

(note: These days I try to get by using the much simpler abduco and the windowing/tabbing features of Vim and terminal emulators like Konsole and Kitty)

Pcat

pcat $filename will print the first 39 lines of the file and apply syntax highlighting.

TUI PIM – Aerc, PimSync, Khal, Khard, Todoman

As a terminal UI fallback for my PIM needs, I use:

• PimSync is responsible to sync calendars and contacts via CalDAV, CardDAV and WebCal. (It is replacement for VDirSync.)
• Khal is a TUI to display and interact with calendars in a standard iCalendar format.
• Todoman is a CLI (with a beta TUI) command to manipulate tasks in a standard iCalendar format.
• Khard is a CLI command to search through and edit contacts in a standard vCard format.
• Aerc is a modern, terminal-based e-mail client that is easier to use than Mutt, and more powerful than Pine. I have it set up, so it also embeds Khal and Todoman to display calendars and tasks. It also uses Khard to look up addresses of contacts.

To get the whole TUI PIM settings suite set-up, do:

stow aerc pimsync khal khard todoman

Regarding CalDAV/CardDAV and WebCal syncing, you may want to also set up a cronjob to trigger pimsync sync regularly (or not forget to run it manually every now and again).

Note: These include my own choice of calendars and servers. Make sure you carefully read and remove/edit the relevant sections in them. As such, the set-up also relies on secret-tool and any Secret Service provider (in my case KeepassXC) to prevent having passwords stored in as plain-text in config files.

Ranger

Ranger is a pretty neat CLI file manager, which I occasionaly use. So far the only change is that I use the Devicons plugin to show Nerd font icons in it.

Temporary Downloads folder

To avoid my downloads folders to become a trashbin-clone, I decided to have it automatically cleaned out regularly.

For this I use Systemd’s TmpFiles to clean up my Downloads and other temporary files every two weeks.

Do not forget to also start the appropriate SystemD timer (and change the relevant user, group and folders, of course):

systemctl --user enable systemd-tmpfiles-clean.timer
systemctl --user start systemd-tmpfiles-clean.timer

More info can be found in man tmpfiles.d and man systemd-tmpfiles.

Firefox template

The firefox_template folder is a bit special, as you cannot simply stow it, because Firefox can have several profiles and therefore they have different names, to not mess with each other.

In short my tweaks to Firefox are:

• better integration with KDE Plasma (incl. window decorations)
• disable AI chatbot and Firefox Accounts/Sync
• enable vertical tabs
• add add-ons I regularly use to the template profile

Read <./firefox_template/README.markdown> for how to properly use it.

FOSS/copyright compliance tools

For my FOSS/copyright compliance work, I created some short scripts to assist me do some common chores that include regular expressions, querying JSON and suchlike, which I find tedious to remember. These all start with foss_*. I am listing them in descending order of wider audience usefuleness.

REUSE wrapper for existing Git repos

Following the specification on https://reuse.software is a great way annotate your own code with appropriate license and copyright notices. It is also super simple to use the reuse tool itself when you start a new repository. But if you are trying to apply it to a pre-existing repository with files of varying age, especially if you want the copyright statements to be exact.

This is what foss_reuse_for_git_repos helps with – it finds the date of the first commit of each file and uses that year in the copyright statement in the REUSE header. For massive repos with a lot of history, this can take some time.

For example, if you want to license an existing repositry under the MIT license and your name is "Da Hacker" you can do the following:

cd $git_repo
foss_reuse_for_git_repos --copyright "Da Hacker <me@hacker.example>" --license MIT

SBOM (SPDX, CycloneDX) queries

There are two major Software Bill of Material (SBOM) standards in use – SPDX and CycloneDX. Previously I relied on grep to search through SPDX tag:value format, but using jq to parse their JSON formats produces more reliable results (at least with my limited skills). As I still find jq a bit convoluted to use and its documentation quite arcane, I created the sbom-search function to handle that.

It can process both SPDX JSON with the --sbom-type=spdx (or -tspdx) flag and CycloneDX JSON with the --sbom-type=cyclonedx (or -tcyclonedx) flag.

Currently you can search for the following fields by use of --field= (or -f) flag:

• component-copyright – lists copyright notices of all of the components in the package
• component-declared-license – list all declared licenses of all of the components in the package
• component-concluded-license – lists all concluded licenses of all of the components in the package
• component-name – lists all names of the components in the package; and more reliably ...
• component-purl – lists all Package URLs of all the components in the package

It even has a --help flag :).

Examples:

sbom-search --sbom-type=spdx --field=component-concluded-license package.spdx.json

sbom-search -tcyclonedx -fcomponent-copyright package.cyclonedx bom.cdx.json

I will likely add more fields to that later.

Find file in ScanCode results

In a similar vain, foss_scancode_filename {$searched_filename} {$scancode_file} lists whole JSON blocks from a ScanCode results file that match the $searched_filename and applies syntax highlighting to it.

This can be useful when you are trying to figure out where (if at all) a certain file comes in and what information is attached to it.

Copyright statement and generated code finder

These tackle a very specific use case, are very stupid and quite hackish:

• foss_how_much_is_mine – lists all Java, JavaScript and TypeScript source (and some binary) code files that do not include a string (intent: copyright statement) passed through the argument
• foss_generated_code – lists all Java, JavaScript and TypeScript source (and some binary) code files that do not inlude the above string and are also marked as @generated

If you want to run foss_generated_code you need to first run foss_how_much_is_mine.

Example:

First run:

cd {$my_source_code}
foss_how_much_is_mine "BigAss Company, Inc"

This will list all files that do not include the string "BigAss Company, Inc" (and therefore we assume are not © BigAss Company) as well as provide a count of all files analysed, those that include said string, and those that do not.

If you then run in the same directory also:

foss_generated_code

It will list all the files that do not include the above string, but that do include the string @generated.

Dependencies

Fish shell

In addition to Fish itself, the following functions have the following run-time dependencies:

• the Ctrl+R key binding for easier searching through history depends on peco
• cascade_kwin depends on KDE’s window manager KWin
• (削除) fancy-diff is a wrapper for diff-so-fancy (削除ここまで) – I recently moved to delta instead
• foss_how_much_is_mine depends on moreutils
• foss_reuse_for_git_repos is a wrapper for the reuse helper tool and Git
• (削除) lshas [lsd][] as an optional dependency, if you havelsdinstalled it will used that, if not, just standardls` (削除ここまで) – I recently moved to eza instead
• pandoc-document and pandoc-slides depend on Pandoc
• pcat depends on bat
• rg-delta depends on RipGrep and delta
• sbom-search depends on jq to query JSON
• (削除) tree depends on tree (and optionally on lsd) (削除ここまで) – I recently moved to eza instead
• abduco is just a wrapper with IMHO saner defaults for abduco – so clearly you need that

Not exactly a dependency, but I incorporated the Hydro Fish prompt and modified it slighlty. And to have the ssh-agent work nicely in Fish, I am using fish-ssh-agent.

My set-up also assumes use of Nerd fonts.

TUI PIM – Aerc, Khal, Todoman, Pimsync

Both Aerc and Pimsync depend on a Secret Service provider, like e.g. KeepassXC and the secret-tool that is packaged in libsecret

For Todoman’s interactive TUI (todo repl) to work, you will need to install Python’s Click Repl – on Arch that package is called python-click-repl.

Aerc is set up to launch also Khal and Todoman – so you may want to install them. It will work OK without them though.

Hyprland

Hyprland being modular, depends on a lot of components that need to be installed separately:

• HyprPaper – used for setting up the wallpaper, I am heavily _under_using it
• Kitty – assumes Kitty as the default terminal emulator
• Wofi – application launcher
• Waybar – desktop panel. Technically it will run without it, but everything will be a bit confusing.
• Dunst – desktop notifications. Technically it will run without it, but everything will be a bit confusing.
• Dolphin – (KDE) file browser
• HyprLock – locks the screen. Technically it will run without it, but a lockscreen is kind of a must-have.

If you do not use those, you will need to change ~/.config/hypr/hyprland.conf accordingly.

The following are optional, and will not break Hyprland if they are not present, but some features will be missing:

• HyprIdle – should trigger the lock screen, sleep and screen brightness after certain periods of time, but I seem to have messed something
• NetworkManager applet – assumes nm-applet to connect to the network and puts it in the
• KeepassXC – password manager – if it exists, it will try to auto-start
• Nextcloud client – sync client for Nextcloud – if it exists, it will try to auto-start

Tmux

This tmux config file is written in a way to show RAM and CPU usage as well as the system’s load.

For this to work, you have to install tmux-mem-cpu-load.

i3

In addition to i3 itself, the following things are needed for some of the functionalities to work as intended:

• i3-volume and dunst for volume control and its OSD (see i3-volume docs for OSD alternatives))
• xbacklight-ctl and dunst for brightness control and its OSD
• compton/picon compositor to enable transparency
• terminology as the terminal emulator (just change it for whatever you prefer)
• feh image viewer to set background images
• rofi as a window switcher and application launcher
• i3lock-fancy to lock the screen in a pretty manner

Troubleshooting

Stow complains

If e.g. during your first stow fish Stow complains like this:

WARNING! stowing fish would cause conflicts:
 * existing target is neither a link nor a directory: .config/fish/config.fish
All operations aborted.

Then simply remove the conflicting file (in this case ~/.config/fish/config.fish) and re-run the command that failed.