.. dotbot-windows -- Configure Windows using dotbot.
.. Copyright 2023-2024 Kurt McKee <contactme@kurtmckee.org>
.. SPDX-License-Identifier: MIT
dotbot-windows
##############
Configure Windows using `dotbot`_.
-------------------------------------------------------------------------------
Table of contents
=================
* `What you can do with it`_
* `Installation`_
* `Configuration`_
* `Development`_
What you can do with it
=======================
The dotbot-windows plugin is able to configure Windows in the following ways:
* Configure the desktop background color
* Import registry files (``*.reg``) from a specified directory
Sample configuration:
.. code-block:: yaml
windows:
personalization:
background-color: "#2A4661"
registry:
import: "my-registry-tweaks/"
fonts:
path: "my-standard-fonts/"
Installation
============
There are two ways to install and use the plugin:
1. Install it as a Python package.
2. Add it as a git submodule in your dotfiles repository.
3. Copy ``dotbot_windows.py`` into your dotfiles directory.
Python package
--------------
If you want to install dotbot-windows as a Python package
(for example, if you're using a virtual environment),
then you can install the plugin using ``pip``:
.. code-block::
pip install dotbot-windows
Then, when running dotbot, use the ``-p`` or ``--plugin`` option
to tell dotbot to load the plugin:
.. code-block::
dotbot [...] --plugin dotbot_windows [...]
If you're using one of dotbot's ``install`` scripts,
you'll need to edit that file to add the ``--plugin`` option.
Git submodule
-------------
If you want to track dotbot-windows as a git submodule
(for example, if you manage your dotfiles using git)
then you can add the plugin repository as a submodule using ``git``:
.. code-block::
git submodule add https://github.com/kurtmckee/dotbot-windows.git
This will clone the repository to a directory named ``dotbot-windows``.
Then, when running dotbot, use the ``-p`` or ``--plugin`` option
to tell dotbot to load the plugin:
.. code-block::
dotbot [...] --plugin dotbot-windows/dotbot_windows.py [...]
Note that you may need to initialize the plugin's git submodule
when you clone your dotfiles repository or pull new changes
to another computer.
The command for this will look something like:
.. code-block::
git submodule update --init dotbot-windows
Copy ``dotbot_windows.py``
--------------------------
If desired, you can copy ``dotbot_windows.py`` to your dotfiles directory.
You might choose to do this if you already use other plugins
and have configured dotbot to load all plugins from a plugin directory.
If you copy ``dotbot_windows.py`` to the root of your dotfiles directory
then, when running dotbot, use the ``-p`` or ``--plugin`` option
to tell dotbot to load the plugin:
.. code-block::
dotbot [...] --plugin dotbot_windows.py [...]
If you copy ``dotbot_windows.py`` to a directory containing other plugins,
you can use dotbot's ``--plugin-dir`` option to load all plugins in the directory.
In the example below, the plugin directory is named ``dotbot-plugins``:
.. code-block::
dotbot [...] --plugin-dir dotbot-plugins [...]
Configuration
=============
**Personalization**
You can configure the desktop background color using a hexadecimal color (like ``"#2A4661"``)
or a triplet of decimal RGB values (like ``"0 153 255"``).
Here are examples demonstrating the two formats:
.. code-block:: yaml
windows:
personalization:
background-color: "#2A4661"
.. code-block:: yaml
windows:
personalization:
background-color: "42 70 97"
**Registry**
You can import registry files by specifying a directory containing ``*.reg`` files.
The directory will be recursively searched for ``*.reg`` files,
and each of them will be imported.
Note that registry imports may fail if the changes require administrator privileges.
Here's a dotbot configuration file example:
.. code-block:: yaml
windows:
registry:
import: "registry-export-files"
**Fonts**
Starting with Windows 10 build 17704, users can `install fonts without admin permissions`_.
The fonts can be copied into ``"%LOCALAPPDATA%/Microsoft/Windows/Fonts"``,
so this plugin replaces that directory with a symlink to a directory of your choosing.
Here's a dotbot configuration file example:
.. code-block:: yaml
windows:
fonts:
path: "my-standard-fonts/"
.. note::
This plugin will only create the symlink -- or update it -- under these circumstances:
* The user's Windows font directory must be an empty directory,
* OR the font directory must already be a symlink
Development
===========
To set up a development environment, clone the dotbot-windows plugin's git repository.
Then, follow these steps to create a virtual environment and run the unit tests locally:
.. code-block:: shell
# Create the virtual environment
$ python -m venv .venv
# Activate the virtual environment (Windows-only)
$ & .venv/Scripts/Activate.ps1
# Update pip and setuptools, and install wheel
(.venv) $ pip install -U pip setuptools wheel
# Install poetry, tox, and scriv
(.venv) $ pip install poetry tox scriv
# Install all dependencies
(.venv) $ poetry install
# Run the unit tests locally
(.venv) $ tox
.. Links
.. =====
..
.. _dotbot: https://github.com/anishathalye/dotbot
.. _install fonts without admin permissions: https://blogs.windows.com/windows-insider/2018/06/27/announcing-windows-10-insider-preview-build-17704/
Raw data
{
"_id": null,
"home_page": "https://github.com/kurtmckee/dotbot-windows",
"name": "dotbot-windows",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dotbot, dotbot-plugin, windows, dotfiles",
"author": "Kurt McKee",
"author_email": "contactme@kurtmckee.org",
"download_url": "https://files.pythonhosted.org/packages/a1/88/524c6aacdba227579858b8ed2cb1404d1e772a72c7d97a6ff0cdbc5d67a6/dotbot_windows-1.1.0.tar.gz",
"platform": null,
"description": ".. dotbot-windows -- Configure Windows using dotbot.\n.. Copyright 2023-2024 Kurt McKee <contactme@kurtmckee.org>\n.. SPDX-License-Identifier: MIT\n\n\ndotbot-windows\n##############\n\nConfigure Windows using `dotbot`_.\n\n-------------------------------------------------------------------------------\n\n\nTable of contents\n=================\n\n* `What you can do with it`_\n* `Installation`_\n* `Configuration`_\n* `Development`_\n\n\nWhat you can do with it\n=======================\n\nThe dotbot-windows plugin is able to configure Windows in the following ways:\n\n* Configure the desktop background color\n* Import registry files (``*.reg``) from a specified directory\n\nSample configuration:\n\n.. code-block:: yaml\n\n windows:\n personalization:\n background-color: \"#2A4661\"\n\n registry:\n import: \"my-registry-tweaks/\"\n\n fonts:\n path: \"my-standard-fonts/\"\n\n\nInstallation\n============\n\nThere are two ways to install and use the plugin:\n\n1. Install it as a Python package.\n2. Add it as a git submodule in your dotfiles repository.\n3. Copy ``dotbot_windows.py`` into your dotfiles directory.\n\n\nPython package\n--------------\n\nIf you want to install dotbot-windows as a Python package\n(for example, if you're using a virtual environment),\nthen you can install the plugin using ``pip``:\n\n.. code-block::\n\n pip install dotbot-windows\n\nThen, when running dotbot, use the ``-p`` or ``--plugin`` option\nto tell dotbot to load the plugin:\n\n.. code-block::\n\n dotbot [...] --plugin dotbot_windows [...]\n\nIf you're using one of dotbot's ``install`` scripts,\nyou'll need to edit that file to add the ``--plugin`` option.\n\n\nGit submodule\n-------------\n\nIf you want to track dotbot-windows as a git submodule\n(for example, if you manage your dotfiles using git)\nthen you can add the plugin repository as a submodule using ``git``:\n\n.. code-block::\n\n git submodule add https://github.com/kurtmckee/dotbot-windows.git\n\nThis will clone the repository to a directory named ``dotbot-windows``.\nThen, when running dotbot, use the ``-p`` or ``--plugin`` option\nto tell dotbot to load the plugin:\n\n.. code-block::\n\n dotbot [...] --plugin dotbot-windows/dotbot_windows.py [...]\n\nNote that you may need to initialize the plugin's git submodule\nwhen you clone your dotfiles repository or pull new changes\nto another computer.\nThe command for this will look something like:\n\n.. code-block::\n\n git submodule update --init dotbot-windows\n\n\nCopy ``dotbot_windows.py``\n--------------------------\n\nIf desired, you can copy ``dotbot_windows.py`` to your dotfiles directory.\nYou might choose to do this if you already use other plugins\nand have configured dotbot to load all plugins from a plugin directory.\n\nIf you copy ``dotbot_windows.py`` to the root of your dotfiles directory\nthen, when running dotbot, use the ``-p`` or ``--plugin`` option\nto tell dotbot to load the plugin:\n\n.. code-block::\n\n dotbot [...] --plugin dotbot_windows.py [...]\n\nIf you copy ``dotbot_windows.py`` to a directory containing other plugins,\nyou can use dotbot's ``--plugin-dir`` option to load all plugins in the directory.\nIn the example below, the plugin directory is named ``dotbot-plugins``:\n\n.. code-block::\n\n dotbot [...] --plugin-dir dotbot-plugins [...]\n\n\nConfiguration\n=============\n\n**Personalization**\n\nYou can configure the desktop background color using a hexadecimal color (like ``\"#2A4661\"``)\nor a triplet of decimal RGB values (like ``\"0 153 255\"``).\n\nHere are examples demonstrating the two formats:\n\n.. code-block:: yaml\n\n windows:\n personalization:\n background-color: \"#2A4661\"\n\n.. code-block:: yaml\n\n windows:\n personalization:\n background-color: \"42 70 97\"\n\n**Registry**\n\nYou can import registry files by specifying a directory containing ``*.reg`` files.\nThe directory will be recursively searched for ``*.reg`` files,\nand each of them will be imported.\n\nNote that registry imports may fail if the changes require administrator privileges.\n\nHere's a dotbot configuration file example:\n\n.. code-block:: yaml\n\n windows:\n registry:\n import: \"registry-export-files\"\n\n\n**Fonts**\n\nStarting with Windows 10 build 17704, users can `install fonts without admin permissions`_.\nThe fonts can be copied into ``\"%LOCALAPPDATA%/Microsoft/Windows/Fonts\"``,\nso this plugin replaces that directory with a symlink to a directory of your choosing.\n\nHere's a dotbot configuration file example:\n\n.. code-block:: yaml\n\n windows:\n fonts:\n path: \"my-standard-fonts/\"\n\n.. note::\n\n This plugin will only create the symlink -- or update it -- under these circumstances:\n\n * The user's Windows font directory must be an empty directory,\n * OR the font directory must already be a symlink\n\n\nDevelopment\n===========\n\nTo set up a development environment, clone the dotbot-windows plugin's git repository.\nThen, follow these steps to create a virtual environment and run the unit tests locally:\n\n.. code-block:: shell\n\n # Create the virtual environment\n $ python -m venv .venv\n\n # Activate the virtual environment (Windows-only)\n $ & .venv/Scripts/Activate.ps1\n\n # Update pip and setuptools, and install wheel\n (.venv) $ pip install -U pip setuptools wheel\n\n # Install poetry, tox, and scriv\n (.venv) $ pip install poetry tox scriv\n\n # Install all dependencies\n (.venv) $ poetry install\n\n # Run the unit tests locally\n (.venv) $ tox\n\n\n.. Links\n.. =====\n..\n.. _dotbot: https://github.com/anishathalye/dotbot\n.. _install fonts without admin permissions: https://blogs.windows.com/windows-insider/2018/06/27/announcing-windows-10-insider-preview-build-17704/\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Configure Windows using dotbot",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/kurtmckee/dotbot-windows",
"Repository": "https://github.com/kurtmckee/dotbot-windows"
},
"split_keywords": [
"dotbot",
" dotbot-plugin",
" windows",
" dotfiles"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db6f4392aad5ccd27f00d8efc2a960362a203cdc035b54115aaccefe17cb0081",
"md5": "3091bff4272c0bc384bac3d61f9a5c98",
"sha256": "5bfe0e5e33c50977b66dcefca4188b659d7b657493e1c034ebf0357ec2f134a4"
},
"downloads": -1,
"filename": "dotbot_windows-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3091bff4272c0bc384bac3d61f9a5c98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7956,
"upload_time": "2024-03-25T13:31:48",
"upload_time_iso_8601": "2024-03-25T13:31:48.125513Z",
"url": "https://files.pythonhosted.org/packages/db/6f/4392aad5ccd27f00d8efc2a960362a203cdc035b54115aaccefe17cb0081/dotbot_windows-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a188524c6aacdba227579858b8ed2cb1404d1e772a72c7d97a6ff0cdbc5d67a6",
"md5": "7fb3a42826bc0f5009cf3151755b2fbc",
"sha256": "3f275d9152c7b755cbdff1c127032e8579c6e4615aa264c0e364e2081f10a4bc"
},
"downloads": -1,
"filename": "dotbot_windows-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7fb3a42826bc0f5009cf3151755b2fbc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7480,
"upload_time": "2024-03-25T13:31:52",
"upload_time_iso_8601": "2024-03-25T13:31:52.435908Z",
"url": "https://files.pythonhosted.org/packages/a1/88/524c6aacdba227579858b8ed2cb1404d1e772a72c7d97a6ff0cdbc5d67a6/dotbot_windows-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-25 13:31:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kurtmckee",
"github_project": "dotbot-windows",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dotbot-windows"
}
JSON
