Setting Up a New Machine

On a new machine

This is what the project was for. On a fresh Ubuntu install (or a new WSL distribution, or a server you log in to), your whole setup is a handful of commands.

1. Install git, which a minimal system may not have:

me@linuxbox:~$ sudo apt install git

2. Give this machine an SSH key and add it to GitHub, as in module 4. One key per machine means you can revoke one without touching the others ¹:

me@linuxbox:~$ ssh-keygen -t ed25519 -C "you@example.com"
me@linuxbox:~$ cat ~/.ssh/id_ed25519.pub

3. Clone, install, and set your name and email:

me@linuxbox:~$ git clone git@github.com:you/dotfiles.git ~/dotfiles
Cloning into '/home/me/dotfiles'...
me@linuxbox:~$ ~/dotfiles/install.sh
linked   ~/.bash_aliases
linked   ~/.inputrc
linked   ~/.nanorc
linked   ~/.config/git/ignore
included gitconfig in ~/.gitconfig
me@linuxbox:~$ git config --global user.name "Your Name"
me@linuxbox:~$ git config --global user.email "you@example.com"
me@linuxbox:~$ cat ~/.gitconfig
[include]
    path = /home/me/dotfiles/gitconfig
[user]
    name = Your Name
    email = you@example.com

On a new machine there are no old files in the way, so everything is just linked. The new ~/.gitconfig holds only the include and this machine’s name and email.

4. Load it. Open a new terminal, or reread the startup file in this one (Shell course, module 5):

me@linuxbox:~$ source ~/.bashrc
me@linuxbox:~$ type mkcd
mkcd is a function
mkcd () 
{ 
    mkdir -p -- "$1" && cd -- "$1"
}
me@linuxbox:~$ alias gl
alias gl='git log --oneline -10'

Your prompt, aliases, history settings, Readline keys, nano settings, and git settings are all in place. Put these steps in the repository’s README.md, so future you doesn’t have to remember them.

Keeping machines in step

Change a setting on any machine, commit, and push. On the others, pull:

me@linuxbox:~/dotfiles$ git push
To github.com:you/dotfiles.git
   f83aa0a..d608458  main -> main

and on the second machine:

me@linuxbox:~/dotfiles$ git pull
From github.com:you/dotfiles
   f83aa0a..d608458  main       -> origin/main
Updating f83aa0a..d608458
Fast-forward
 bash_aliases | 1 +
 1 file changed, 1 insertion(+)

Since the home-folder files are links, the pull updates them too; open a new terminal to pick up shell changes. If you’ve added a new file to LINKS, run ./install.sh again after pulling, which is exactly why it’s safe to rerun.

If you forget to pull before changing something, it’s the same as any repository: the push is rejected, and git pull --rebase then git push sorts it out (module 4). Small commits make that painless.

Settings for one machine only

Some settings shouldn’t be shared: a work email, a folder that only exists on one computer, a server’s prompt color. Missing Semester suggests a few tricks ²:

A local file that’s sourced if it exists. That’s the ~/.bash_local block at the end of bash_aliases. On a machine that needs something extra, create ~/.bash_local there; it’s not in the repository, so it stays on that machine:

# ~/.bash_local on the backup server only
PS1='\[\e[1;31m\]\u@\h\[\e[0m\]:\w\$ '    # red prompt: careful, this is the server
export BACKUP_DEST=/mnt/backup

Because bash_aliases reads it last, anything in it overrides the shared settings.

Git’s includes. ~/.gitconfig is already per-machine. For a different email only in work repositories, git’s conditional include applies a file only when the repository is in a given folder ³:

# in ~/.gitconfig on the work laptop
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

with ~/.gitconfig-work holding [user] and email = you@work.example. A pattern ending in / matches that folder and everything inside it ³.

A test in the shared file, when the difference is small and you’d rather keep it in git ^{2 4}:

if [[ "$(hostname)" == "garden-server" ]]; then
    alias logs='journalctl -f'
fi

What never goes in

A dotfiles repository is easy to treat as “my settings folder” and push without a second look. Keep these out, even of a private repository:

• Private keys: ~/.ssh/id_ed25519 and friends. Each machine makes its own (module 4). ~/.ssh/config, which lists hosts and usernames, is safe if you’re comfortable with what’s in it.
• Tokens and passwords: API tokens, personal access tokens, .netrc, anything with “secret” in it. If a program’s config file mixes settings and a token, put the token in ~/.bash_local or a separate file that’s not in the repository.
• History and caches: ~/.bash_history holds every command you’ve typed, passwords included if you ever typed one.

Before each push, git diff --staged (module 2) is a quick look at exactly what’s going out. And if a secret does get committed, deleting it in the next commit isn’t enough: it’s in the history (module 6), so change the secret (module 2).

Other ways to do it

The folder-plus-links approach is the one Missing Semester recommends, but it isn’t the only one. Three you’ll see:

• A bare repository in your home folder. Popularized on Hacker News and described in the Arch Wiki: git init --bare ~/.dotfiles, an alias like alias dotfiles='/usr/bin/git --git-dir="$HOME/.dotfiles/" --work-tree="$HOME"', and dotfiles config status.showUntrackedFiles no. The files stay at their real paths with no links, and you use dotfiles add, dotfiles commit, and so on ⁴. The cost is that git’s view of your home folder is easy to confuse.
• GNU Stow, a “symlink farm manager”: arrange the repository in folders that mirror your home folder (bash/.bash_aliases, nano/.nanorc), then stow bash makes the links ⁵. It replaces install.sh with a convention.
• Dotfile managers like chezmoi, which add templates for per-machine differences. The Arch Wiki keeps a comparison table ⁴.

Your script is small, tested, and does exactly what you understand, and you can switch later; your files and their history come with you.

Your turn

So

On a new machine: install git, make an SSH key, clone ~/dotfiles, run install.sh, set your name and email, and open a new terminal. After that, commit and push changes from wherever you make them, and pull everywhere else. Machine-only settings go in ~/.bash_local, ~/.gitconfig (with includeIf for folders), or a hostname test; keys, tokens, and history never go in the repository. That finishes the Git course: you can now version, branch, share, repair, and understand your work, and carry your whole command-line setup to any Linux machine.