Git on juni's blog ٩(◕‿◕｡)۶

Tracking & Syncing my dotfiles!

Sun, 22 Jun 2025 00:00:00 +0000

.dotfiles or… (.)²files?

- Using Git + Github, & tracking dotfiles with an alias.

… as mentioned on the ever-wise Arch Wiki.

# 1. Create a bare Git repo to track dotfiles
git init --bare ~/.dotfiles

# 2. Create an alias to simplify dotfiles management.
# Tells (/usr/bin/git) to link the git alias directory you just created to your real .config/
alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'

# 3. Hide untracked files in ~/ from cluttering "git status"
dotfiles config status.showUntrackedFiles no

Setup & communicate with this repo via ssh, authenticating with a local private key.

# 4. Generate SSH key for GitHub auth (if you haven't got one already)
ssh-keygen -t ed25519 -C "you@example.com"
ssh-add ~/.ssh/id_ed25519

# Add the value of ~/.ssh/id_ed25519.pub as an entry in your Github --> Settings --> SSH & GPG Keys, via cat + copy-pasting, or however you'd like.

# 5. Force git on your machine to always push to github with SSH instead of HTTPS
git config --global url."git@github.com:".insteadOf "https://github.com/"

# 6. Set upstream branch as origin main & push via ssh!
dotfiles push --set-upstream origin main

then, upon changing my dotfiles, can push to github with:

dotfiles status
dotfiles add XXXXX
dotfiles commit -m "Update shell and Hyprland config"
dotfiles push (to remote, via SSH)

- or… using a dotfiles manager, comme `chezmoi`.

… which is a tool that essentially creates a copy of your dotfiles folder outside of your /home directory (e.g. in ~/.local/share/chezmoi/private_dot_config/) to act as a place to stage, synchronise (with git) & manage changes to your local dotfiles.

I think of it as a remotely-connected playground for your dotfiles, to mess with them, pull them from remote repos etc., before applying the changes (via symlinks, copying, or templating) into your local home directory (e.g. ~/.config).

- To install:

sudo pacman -S chezmoi
chezmoi init
Check what is & isn’t managed by chezmoi with chezmoi managed/chezmoi unmanaged.
… then follow steps on this tutorial to connect to your repository & get your first commit. I’m using chezmoi to push to the same remote dotfiles repo created above, and so just rebased my changes (overwriting the old, chezmoi-less dotfiles from above) to keep it nice and clean.

- Editing your dotfiles & using `chezmoi`:

You can edit your dotfiles in multiple ways with chezmoi.

(`RECOMMENDED`) You can work and make changes within the locally-created `chezmoi` copy of your `dotfiles`, apply them locally, and push them to remote repo once done.

Navigate to your chezmoi dotfiles copy with chezmoi cd (you should be able to tell that it’s the chezmoi-managed copy - e.g. it’s called private_dot_config for me).
Then, once you’ve made changes and are ready to see them/apply them to your real dotfiles (e.g to see changes live made to your desktop GUI), use chezmoi status to list all changed files, chezmoi diff to check any changes, and chezmoi apply to copy the chezmoi-managed files over to your local dotfiles. Now, you should see any changes made reflected on your live system (after reloading the given services, if applicable)
Then², once you’re ready to update your remote repo with your changes, go through the usual git commit process within the chezmoi-managed directory.
git status to see all changed files (within the chezmoi-managed copy)
git add . (or whatever files you want to add)
git commit -m "cool changes
git push origin main

However, you also have the option of…

…making changes to your dotfiles normally (i.e. not within the `chezmoi`-managed copy of your `dotfiles`)

So, after you’re finished a particularly spicy ricing session, you can run:

chezmoi status - to see what’s changed between your local dotfiles and chezmoi’s copy.
chezmoi add ~/.config/path/to/file.config - to add any locally-changed files to chezmoi’s tracked & git-managed copy.
chezmoi apply -v to write these local changes to chezmoi's working copy of your dotfiles.
Then switch to the chezmoi-managed copy with cd chezmoi, and go through the usual git commit process to update your remote repo if desired.

chezmoi, importantly, allows you to do some of the following cool things:

Set up your dotfiles on a new machine with a single command: chezmoi init --apply https://github.com/$GITHUB_USERNAME/dotfiles.git (public repo - private requires other methods)
Using templates to manage dotfiles between different machines/distros.
Encrypting your dotfiles using secrets from your password manager

building & deploying this blog with hugo!

Wed, 08 Jan 2025 00:00:00 +0000

and now - to the story of how this blog was born!

(it’s nothing special, but I thought I’d document it for myself when i inevitably forget how i did it in the future, as well as any other wandering lost souls out there!)

i’ve been meaning to re-jig my tech blog for a while now. for the last year and a bit, I experimented with the static site generator (SSG) jekyll. jekyll is essentially a tool built in ruby that combines blog posts (typically written in markdown, .md files) with themes/config files to generate browser-renderable code (HTML, CSS and JS).

this way, you can streamline your workflow, embed all sorts of cool features (comments, reactions, reading times, table of contents, automatic rss feeds, post dating etc.), and most importantly avoid the horror of writing blog posts in raw HTML… but still being able to dabble in it when you please (providing your markdown-to-html renderer permits that).

…and all of this within a static site (all files pre-built on web-server, no databases) that is lightweight, responsive, maintainable and (relatively) quick to spin up.

- why did i move away from jekyll?

for three simple reasons:

i’d been meaning to try the SSG hugo.
hugo is built in golang, and i’d been wanting to poke around with go for a while now.
i found (and confirmed, after trying hugo) ruby & jekyll to be a bit more onerous to work with & overly-verbose in both site layout & base code. also - i noticed that jekyll had much slower build times.

- getting up and running with hugo:

there are endless tutorials for this, and my pipeline is probably most similar to that of NetworkChuck in the recent video he released (not even a week before I went in on my own build, after sitting on the idea for ages haha - twas kinda spoopy :3).

- setting up the hugo site:

Hugo has two simple dependencies: git (for code version control), and the go compiler toolchain. (here are where you can install git and go, if needed)
after installing these, using the package manager of your choice (for me, homebrew), install hugo with brew install hugo.
choose a directory for your site, and open it in your code editor. ensure hugo is in your system PATH so you can access it via the command line, and run hugo -v to ensure you’re on the latest.
then simply run hugo new site [SITENAME], replacing [SITENAME] with whatever you’d like to call the site (& folder it lives in). hugo will then spinup the basic bones of your site, and navigate into the folder it creates with cd.
initialise an empty git repository in this new folder with git init.
to install a theme, browse them here, and follow the instructions in the theme’s description (as some methods vary). however, the most common is installation is via a git submodule - which essentially will just pull down an existing git repo containing a pre-built hugo theme, and populate your site’s themes folder with it. this way, when building your site, hugo will use it as a base layout, and add any changes made to your site on top of it. for me, i ran: git submodule add https://github.com/michaelneuper/hugo-texify3.git themes/hugo-texify3
now, your site’s directory tree should look something like the following:

Folders & files are fairly self-explanatory, with the main ones being:
- hugo.toml - your site’s configuration variables.
- /content - where you create folders to store blog posts (.md) & site pages
- /assets - ideally where media is stored & linked (although you can place them anywhere, theoretically, providing you link back to it correctly)
- /public (only created when website is built, see step 8.) - where your raw website (raw HTML, CSS, JS) will be built to and live. you shouldn’t need to touch this folder.
- /themes - where all of your sites themes are installed (and specified/switched between in hugo.toml)
sometimes, themes require installing other tools as part of their custom build process. this should be specified in the theme’s documentation. for me, that required needing to install the following with npm: npm install postcss-cli autoprefixer postcss-import
to build your site locally, ensure you’re in your site’s base directory and run hugo server -t [THEME-NAME] (if using a theme). for me: hugo server -t hugo-texify3
now, navigate to the local address to see your site in action! it should live-reload as you make changes in your code editor.
[EXTRA] after analysing my specific theme’s layout & directory structure, I mirrored elements of it (thus overwriting what was contained in the /themes folder) to create the below folder structure, allowing me to: - add dedicated website pages in /pages - use /posts to hold my site post, with each in its own folder alongside any assets (images, media, etc.). this was done due to my particular workflow (writing in obsidian, see below). - split site configuration into two files for readability in /config: one for parameters (enabling/disabling certain features like social links, metadata etc.), and one for overall config & layout.

- pushing to remote git repository & deploying via cloudflare pages

(aka my weird custom workflow):

after running git init, ensure you are authenticated locally with gh auth login (requires use of Github CLI, install with brew install gh or similar)
create a new repository on GitHub with: gh repo create juni-blog --public --source=. --remote=origin
- --public: sets repo as public, as cloudflare will need to monitor it for changes
- --source=.: initialises the remote repository with your current local directory’s contents
- --remote=origin: sets up the remote URL for the repository
now, just push the local branch to the remote with git push -u origin main.

The -u (or --set-upstream) option in git push links your local branch (main) to the remote branch (origin) by default, allowing you to run git push and git pull commands in the future without adding origin main at the end (AKA specifying which remote branch to interact with by default).
navigate to your remote repository on github to check whether the changes have been propagated!
setup, login to and open cloudflare pages and navigate to your Workers & Pages section, then Create to deploy a new “site”. The click Connect to Git and follow the prompts to authenticate, and link to the repository that you just pushed to.

After that, you can specify which branch Cloudflare should look for changes on, as any frameworks that you’re using to build & deploy the site, and where the built assets & HTML files are stored. I selected Hugo (for obvious reasons), and it populated the build command with a simple hugo.

However, if your site requires other tools as part of the build process like mine (specified in step 8 in the previous section), be sure to install them on the remote server this site is running off with the relevant commands. for me, these are: npm install postcss-cli autoprefixer postcss-import && hugo Cloudflare should provide logs from the remote server should your build fail, making troubleshooting fairly simple.
then you’re all set! cloudflare will now watch for any changes made to the specified branch of this repo (for me, main), and if detected, it will automatically run npm install postcss-cli autoprefixer postcss-import && hugo on its remote server(s) to build the updated version of my site, and then serve only the created HTML, CSS & JS files in the specified output directory (for me, public). you should be able to access your site from the default URL created and provided to you, like https://b3ce9f44.juni-blog.pages.dev/.
[extra] to change this URL to a custom domain that you own, go to the Custom Domain section of the page you just created, click Set up a custom domain.

Then, follow the prompts. In my case, I associated the myblog CNAME with this “Page” (juni-blog.pages.dev).

Then, simply navigate to your domain’s (juni-mp4.com) DNS records (for me, also managed via Cloudflare) and add a record for the CNAME you just specified.

This means that when someone visits myblog.juni-mp4.com, they will functionally be visiting juni-blog.pages.dev.

this combination of github & cloudflare pages allows me to easily host & deploy sites from different github repos, each built with all kinds of different build methods (from hand-coding raw HTML/CSS/JS to using various SSGs like jekyll, hugo etc.), as subdomains of my primary domain juni-mp4.com and all served securely & quickly from Cloudflare’s worldwide array of web servers. (not sponsored haha - the only thing you monetarily pay for is your domain registration fee, and even that is optional.)

Side note: yes, whilst you could argue that you “pay” in the form of you & your content being technically in the hands of cloudflare, outside of hosting file files yourself on a VPS or a home server - which comes with a slew of additional overhead, maintenance and security configuration concerns - this is a fairly reasonable compensation to make for the uptime, security & responsiveness that Cloudflare’s network of servers provides, at least imho and for my use case.

this very particular workflow & need for flexibility is why i chose to use cloudflare instead of just deploying straight from Github Pages.

- my final note-taking process: an overview

open my Obsidian “blog” vault, and create a new note within a folder in posts:

the Templater plugin auto-generates the hugo-formatted frontmatter you see above in every new note, using the code block below inside the template file.
```
---
title: ""
date: <% tp.file.creation_date("YYYY-MM-DD") %>
description: ""
toc: true
math: true
draft: true
categories: 
tags:
---
```
write the post :3. drag & drop / copy-paste images as needed, after making sure the Absolute path in vault option is selected in your vault’s Files and links settings. This may need to be tweaked depending on your site’s layout later, but it worked for me, and is easily changed in bulk in VSCode or a similar editor via find & replace.
once I’m finished writing, I switch to my full website directory tree in VSCode (my Obsidian “blog” vault is just the website’s content folder, hence the .obsidian folder inside it).

i run the build command hugo server -t [theme-name-here] in the VScode terminal to start a live server, and visit http://localhost:1313/ to double check that the changes have been formatted properly.
then a simple git commit -m "new blog post: hugo site build" -a && git push origin main pushes the changes to my site where it’s rebuilt & served as new HTML pages!