This repository contains a curated and version-controlled set of configuration files (dotfiles) aimed at establishing a secure, consistent, and productive development environment. It is designed with NHS engineers in mind but can be reused or adapted by any individual or team who wants to bootstrap their development setup across macOS, Linux, and Windows Subsystem for Linux (WSL).
Dotfiles are hidden files that define preferences and behaviours for tools like terminals, shells, editors, and system utilities. Managing them centrally helps reduce setup time, ensures consistency, and enables portability of developer environments.
This setup is optimised for Developer Experience (DX) and is aligned with an Internal Developer Platform (IDP) model, supporting NHSโ broader software delivery strategy.
Refer to the Unofficial guide to dotfiles on GitHub for general dotfiles background.
- ๐ ๏ธ NHS Dotfiles
This project is for NHS engineers, digital teams, and contributors who want a fast, reliable, and secure way to configure their development environment. It supports cross-platform setups and includes preconfigured support for common engineering tools.
- Shell environment (Zsh and Bash) with themes, prompts, aliases, and completions
- Git and GitHub configuration with commit signing support
- Visual Studio Code preferences and recommended extensions
- Secrets integration using Bitwarden
- Platform-specific defaults for macOS, Ubuntu, and WSL
- Secure, opinionated defaults for improved security and compliance
# Install chezmoi and apply NHS dotfiles in one step
bash -c "$(curl -fsLS get.chezmoi.io)" -- init --apply "nhs-england-tools"
For detailed setup and configuration options, see the Installation section.
Before installing this dotfiles configuration, ensure you have the following:
- macOS 10.15+, Ubuntu 20.04+, or Windows 10+ with WSL2
- Git 2.28 or newer
- Zsh shell
- Terminal with Unicode and true color support
- Administrator access (for system package installation)
- Permission to modify shell configuration
- SSH key configured for GitHub access
This dotfiles repository is configured and managed by the chezmoi
project. chezmoi, pronounced /สeษช mwa/ (shay-moi) is currently the most complete and most hackable dotfiles manager out there.
Prior to applying any changes to your home directory, create a backup of your current configuration. This command creates an archive file in the temporary directory that can be used later to restore the configuration, if needed.
tar -czvf /tmp/home-directory-backup.tar.gz -C ~ .
Depending on your OS and terminal settings, you may be prompted to grant access permissions during backup. This is expected and ensures all relevant configuration files are captured. However, if the above takes too long as it archives all the files in your home directory an alternative would be to use chezmoi
to backup only the dotfiles. Please follow the installation guide specific to your operating system before proceeding.
Backups may include sensitive files. Ensure you store them securely if transferring between machines.
chezmoi archive --output=/tmp/dotfiles-backup.tar.gz
The following instruction clones the dotfiles repository into the ~/.local/share/chezmoi/
directory and next applies changes accordingly, to your home directory ~/
. During the setup it prompts you to provide configuration options like Git committer name and email address, etc.
bash -c "$(curl -fsLS get.chezmoi.io)" -- init --apply "nhs-england-tools"
For detailed information about chezmoi
configuration and usage, see the Chezmoi usage guide.
To store some of the configuration options, chezmoi
can use a password manager. Therefore, after the dotfiles installation, please follow the Bitwarden setup guide to improve the installation experience for any subsequent run.
Note
If the Bitwarden CLI is available on your system (this will happen after the first installation of the dotfiles), any subsequent run will use the Bitwarden CLI for password management and prompt you for your Bitwarden password.
Hereโs a complete instruction set to re-apply your dotfiles manually after the initial installation using chezmoi:
# Navigate to your chezmoi working directory
cd ~/.local/share/chezmoi
# Pull the latest changes from your dotfiles source repo
chezmoi update
# Or, re-apply everything from your local configuration
chezmoi apply
# To update the dotfiles from your fork from the current directory (not ~/.local/share/chezmoi), you can use
chezmoi apply --source .
If youโve made changes to your chezmoi.toml
or templates, or switched branches, you can also re-initialise:
# Re-initialise from your fork (e.g. after switching branches or repos)
chezmoi init --apply git@github.com:<your-username>/dotfiles.git
You can simulate the changes that would be applied without making them using:
chezmoi diff
To only re-apply a specific file (e.g. .zshrc):
chezmoi apply ~/.zshrc
This project manages files like:
~ ($HOME)
โ
โโโโ .aliases
โโโโ .bash_profile
โโโโ .bash_prompt
โโโโ .bashrc
โโโโ .exports
โโโโ .functions
โโโโ .gitattribute
โโโโ .gitconfig
โโโโ .gitignore
โโโโ .gitmessage
โโโโ [.macos|.ubuntu]
โโโโ .p10k.zsh
โโโโ .path
โโโโ .zshrc
Some changes use imperative (non-declarative) scripts, written to be idempotent and applied only when necessary.
You can fork this project to customise it for your own environment and workflow.
For a practical example of how this repository can be forked and customised, see stefaniuk/dotfiles, which is a downstream fork maintained and configured by the author. This example demonstrates how to adapt the NHS dotfiles for personal use, apply local preferences, and keep in sync with upstream changes.
- โก Oh My Zsh with Powerlevel10k theme
- ๐ Productivity aliases and functions
- ๐ Environment variables management
- ๐งฉ Custom prompts and autocompletions
- ๐ GNU-compatible CLI tools for consistent experience across supported operating systems
- ๐ Visual Studio Code as default editor
- ๐ Custom settings and keybindings
- ๐งฉ Recommended extensions
- ๐ง Git configuration
- ๐ Signed commits
- ๐ OS-specific ignore rules
- ๐ Git aliases and branch helpers
- ๐งช Toolchain support
- ๐จ TypeScript (JavaScript ecosystem), Node.js, npm
- ๐ Python, pip, uv
- ๐ณ Containers integration
- โ๏ธ GPG commit signing
- ๐ SSH key management
- ๐งฐ Bitwarden password integration
- ๐งฑ Secure-by-default settings
- ๐ macOS
- ๐ง Linux/Ubuntu
- ๐ช Windows WSL (coming soon)
- โ๏ธ GitHub Codespaces
To maintain your own customisations while regularly synchronising with upstream updates, itโs recommended to create a separate branch, commonly called custom
. This approach keeps your local changes isolated from the main branch, makes updates easier to manage, and helps you avoid conflicts.
# Clone your fork of the dotfiles repository
git clone git@github.com:<your-username>/dotfiles.git
cd dotfiles
git checkout main
# Create and switch to your persistent custom branch, if it doesn't exist yet
git checkout custom || git checkout -b custom
# For each set of changes, create a feature branch from custom
git checkout -b your-custom-branch
# Make your custom changes ...
git add .
git commit -S -m "Short, descriptive summary of your custom changes"
git push origin your-custom-branch
# Open a pull request on GitHub and merge your feature branch into custom ...
# After merging on GitHub, clean up local and remote feature branches
git checkout custom
git pull origin custom
git branch -D your-custom-branch
git push origin --delete your-custom-branch
# Periodically update your fork with the latest changes from upstream
git checkout main
git fetch upstream
git merge upstream main
git push origin main
# Rebase your custom branch onto the updated main branch
git checkout custom
git rebase main
git push origin custom --force-with-lease
# (Optional) Squash your custom branch to a single commit
git checkout custom
git reset --soft $(git merge-base custom main)
git add .
git commit -S -m "Squashed: All custom changes up to $(date +"%A, %d %B %Y, %H:%M:%S %Z")"
git push origin custom --force-with-lease
This method preserves a clean history, keeps your changes separate, and makes future updates straightforward.
While it is possible to keep all your changes on the main
branch, doing so means you will need to manually resolve any conflicts each time you pull updates from the original repository. This can become complicated, especially as more changes are made both locally and upstream. For most users, using a dedicated custom
branch is simpler, safer, and helps avoid these issues.
To contribute improvements, features, or fixes to the upstream repository, follow the standard GitHub workflow:
# Ensure your local repository has the latest changes from upstream
git fetch upstream
git checkout upstream/main
# Create a new feature branch based on the latest upstream/main
git checkout -b your-contribution-branch
# Make your changes ..., then stage and sign your commit
git add .
git commit -S -m "Short, descriptive summary of your contribution"
# Push your contribution branch to your fork on GitHub
git push origin your-contribution-branch
# Open a pull request on GitHub ...
# - Set your fork and feature branch as the source
# - Set the upstream repository and its main branch as the target
# - Add a clear title and description for reviewers
# After your pull request is merged on GitHub, you can safely delete the local branch
git checkout main
git pull origin main
git branch -D your-contribution-branch
# Next, follow the "Keep Your Repository Up to Date" section to update your branches with any new upstream changes
Your contribution will be reviewed by maintainers and, if accepted, merged into the official repository for others to benefit from.
After installation, Chezmoi will generate a configuration file at ~/.config/chezmoi/chezmoi.toml
. You can customise it to personalise your dotfiles setup with variables such as:
dotfiles.name
- Your full namedotfiles.email
- Your email addressdotfiles.git_signingkey
- GPG key ID for commit signing
Edit tracked config files:
chezmoi edit ~/.gitconfig
Comprehensive guides are available for various aspects of this dotfiles setup:
- ๐ Chezmoi Usage - Dotfiles manager setup and usage
- ๐ Bitwarden Usage - Password manager integration
- ๐ Git Usage - Version control setup and workflows
- ๐ณ Containers Usage - Container management
- ๐ป Visual Studio Code Usage - Editor configuration
- โ๏ธ System Usage - General system configuration
- ๐งฎ Terminal Usage - Terminal setup and customization
-
GPG signing issues
# Verify GPG key setup gpg --list-secret-keys --keyid-format LONG
-
Zsh configuration problems
# Reset Zsh configuration chezmoi apply ~/.zshrc
The longstanding mathiasbynens/dotfiles project, with its well-established practices and features, has served as an inspiration for improving the Developer Experience in NHS England. It has been adapted and revamped to align with the organisation's strategy.
We welcome contributions to improve and extend this project. Please follow the standard GitHub flow (fork โ branch โ pull request), and ensure your commits are signed.
For larger changes, open a discussion or issue first to align on the approach.
The LICENCE.md file will need to be updated with the correct year and owner
Unless stated otherwise, this codebase is licensed under the MIT Licence, which applies to both the source code and any sample code within the documentation.
All HTML or Markdown documentation is ยฉ Crown Copyright and available under the terms of the Open Government Licence v3.0.