.. dotbot-firefox -- Configure your Firefox profile(s) using dotbot.
.. Copyright 2022-2023 Kurt McKee <contactme@kurtmckee.org>
.. SPDX-License-Identifier: MIT
dotbot-firefox
##############
Configure your Firefox profile(s) using `dotbot`_.
-------------------------------------------------------------------------------
Table of contents
=================
* `What you can do with it`_
* `Installation`_
* `Configuration`_
* `Firefox profile locations`_
* `Development`_
What you can do with it
=======================
When Firefox starts, it will look for a ``user.js`` file in your profile directory.
If found, the ``user.js`` settings will be copied to ``prefs.js`` and used.
You can enforce a consistent Firefox configuration across all your profiles
by using dotbot-firefox to create symlinks to a custom ``user.js``.
The plugin will find Firefox profile directories that contain a ``prefs.js`` file
and will use dotbot's builtin Link plugin to create the symlinks.
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_firefox.py`` into your dotfiles directory.
Python package
--------------
If you want to install dotbot-firefox 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-firefox
Then, when running dotbot, use the ``-p`` or ``--plugin`` option
to tell dotbot to load the plugin:
.. code-block::
dotbot [...] --plugin dotbot_firefox [...]
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-firefox 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-firefox.git
This will clone the repository to a directory named ``dotbot-firefox``.
Then, when running dotbot, use the ``-p`` or ``--plugin`` option
to tell dotbot to load the plugin:
.. code-block::
dotbot [...] --plugin dotbot-firefox/dotbot_firefox.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-firefox
Copy ``dotbot_firefox.py``
--------------------------
If desired, you can copy ``dotbot_firefox.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_firefox.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_firefox.py [...]
If you copy ``dotbot_firefox.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
=============
First, create a ``user.js`` file in the dotfiles directory that dotbot manages.
For example, it could contain this configuration to set your homepage:
.. code-block:: js
user_pref("browser.startup.homepage", "https://dashboard.example");
(MozillaZine maintains an extensive list of `Firefox configuration settings`_.)
Then, add a ``firefox`` directive to your dotbot config with a ``user.js`` key.
The value of the key follows the syntax of the `dotbot Link plugin`_.
.. code-block:: yaml
# Example 1:
# "user.js" can be specified as a string.
firefox:
user.js: firefox/user.js
# Example 2:
# "user.js" can have no value, and will be found
# in the same directory as your dotbot config file.
firefox:
user.js:
# Example 3:
# The extended Link plugin syntax is supported.
firefox:
user.js:
path: firefox/user.js
force: true
Firefox profile locations
=========================
The dotbot-firefox plugin is aware of the following default directories:
* ``%APPDATA%\Mozilla\Firefox\Profiles`` (Windows)
* ``~/Library/Application Support/Firefox/Profiles`` (Mac OS)
* ``~/.mozilla/firefox`` (Linux)
* ``~/snap/firefox/common/.mozilla/firefox`` (Firefox Snap for Linux)
* ``~/.var/app/org.mozilla.firefox/.mozilla/firefox`` (Firefox Flatpak for Linux)
Only profile subdirectories that contain a ``prefs.js`` file
will be considered valid by the plugin.
Development
===========
To set up a development environment, clone the dotbot-firefox 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 (Linux)
$ . .venv/bin/activate
# Activate the virtual environment (Windows)
$ & .venv/Scripts/Activate.ps1
# Update pip and setuptools, and install wheel
(.venv) $ pip install -U pip setuptools wheel
# Install poetry and tox
(.venv) $ pip install poetry tox
# Install all dependencies
(.venv) $ poetry install
# Run the unit tests locally
(.venv) $ tox
.. Links
.. =====
..
.. _dotbot: https://github.com/anishathalye/dotbot
.. _dotbot Link plugin: https://github.com/anishathalye/dotbot#link
.. _Firefox configuration settings: https://kb.mozillazine.org/About:config_entries
Raw data
{
"_id": null,
"home_page": "https://github.com/kurtmckee/dotbot-firefox",
"name": "dotbot-firefox",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "dotbot,dotbot-plugin,firefox,dotfiles",
"author": "Kurt McKee",
"author_email": "contactme@kurtmckee.org",
"download_url": "https://files.pythonhosted.org/packages/05/8c/260cafb074cedab0b6aaec4d55433971773fd8cb21d4dba78abd1652ced5/dotbot_firefox-1.1.0.tar.gz",
"platform": null,
"description": ".. dotbot-firefox -- Configure your Firefox profile(s) using dotbot.\n.. Copyright 2022-2023 Kurt McKee <contactme@kurtmckee.org>\n.. SPDX-License-Identifier: MIT\n\n\ndotbot-firefox\n##############\n\nConfigure your Firefox profile(s) using `dotbot`_.\n\n-------------------------------------------------------------------------------\n\n\nTable of contents\n=================\n\n* `What you can do with it`_\n* `Installation`_\n* `Configuration`_\n* `Firefox profile locations`_\n* `Development`_\n\n\nWhat you can do with it\n=======================\n\nWhen Firefox starts, it will look for a ``user.js`` file in your profile directory.\nIf found, the ``user.js`` settings will be copied to ``prefs.js`` and used.\n\nYou can enforce a consistent Firefox configuration across all your profiles\nby using dotbot-firefox to create symlinks to a custom ``user.js``.\nThe plugin will find Firefox profile directories that contain a ``prefs.js`` file\nand will use dotbot's builtin Link plugin to create the symlinks.\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_firefox.py`` into your dotfiles directory.\n\n\nPython package\n--------------\n\nIf you want to install dotbot-firefox 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-firefox\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_firefox [...]\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-firefox 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-firefox.git\n\nThis will clone the repository to a directory named ``dotbot-firefox``.\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-firefox/dotbot_firefox.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-firefox\n\n\nCopy ``dotbot_firefox.py``\n--------------------------\n\nIf desired, you can copy ``dotbot_firefox.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_firefox.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_firefox.py [...]\n\nIf you copy ``dotbot_firefox.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\nFirst, create a ``user.js`` file in the dotfiles directory that dotbot manages.\nFor example, it could contain this configuration to set your homepage:\n\n.. code-block:: js\n\n user_pref(\"browser.startup.homepage\", \"https://dashboard.example\");\n\n(MozillaZine maintains an extensive list of `Firefox configuration settings`_.)\n\nThen, add a ``firefox`` directive to your dotbot config with a ``user.js`` key.\nThe value of the key follows the syntax of the `dotbot Link plugin`_.\n\n.. code-block:: yaml\n\n # Example 1:\n # \"user.js\" can be specified as a string.\n firefox:\n user.js: firefox/user.js\n\n\n # Example 2:\n # \"user.js\" can have no value, and will be found\n # in the same directory as your dotbot config file.\n firefox:\n user.js:\n\n\n # Example 3:\n # The extended Link plugin syntax is supported.\n firefox:\n user.js:\n path: firefox/user.js\n force: true\n\n\nFirefox profile locations\n=========================\n\nThe dotbot-firefox plugin is aware of the following default directories:\n\n* ``%APPDATA%\\Mozilla\\Firefox\\Profiles`` (Windows)\n* ``~/Library/Application Support/Firefox/Profiles`` (Mac OS)\n* ``~/.mozilla/firefox`` (Linux)\n* ``~/snap/firefox/common/.mozilla/firefox`` (Firefox Snap for Linux)\n* ``~/.var/app/org.mozilla.firefox/.mozilla/firefox`` (Firefox Flatpak for Linux)\n\nOnly profile subdirectories that contain a ``prefs.js`` file\nwill be considered valid by the plugin.\n\n\nDevelopment\n===========\n\nTo set up a development environment, clone the dotbot-firefox 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 (Linux)\n $ . .venv/bin/activate\n\n # Activate the virtual environment (Windows)\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 and tox\n (.venv) $ pip install poetry tox\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.. _dotbot Link plugin: https://github.com/anishathalye/dotbot#link\n.. _Firefox configuration settings: https://kb.mozillazine.org/About:config_entries\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Configure your Firefox profile(s) using dotbot",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/kurtmckee/dotbot-firefox",
"Repository": "https://github.com/kurtmckee/dotbot-firefox"
},
"split_keywords": [
"dotbot",
"dotbot-plugin",
"firefox",
"dotfiles"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "41cfa049d225cc71a51d42bbf77af2deccbc5781e4573776e2034def75b36a43",
"md5": "684b0b0b88eebadaa4683753182c083b",
"sha256": "ec13121aa957ff2ce17f616c0d664af554605870419d79bc01296e6b6f7c95e3"
},
"downloads": -1,
"filename": "dotbot_firefox-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "684b0b0b88eebadaa4683753182c083b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5389,
"upload_time": "2023-05-23T13:35:25",
"upload_time_iso_8601": "2023-05-23T13:35:25.385742Z",
"url": "https://files.pythonhosted.org/packages/41/cf/a049d225cc71a51d42bbf77af2deccbc5781e4573776e2034def75b36a43/dotbot_firefox-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "058c260cafb074cedab0b6aaec4d55433971773fd8cb21d4dba78abd1652ced5",
"md5": "dc4a138e950e571ef96391db6b966e12",
"sha256": "8374b0352f4b77114e18f270e8063ddc36d5c0b7ec599c58001af0078e71a7c6"
},
"downloads": -1,
"filename": "dotbot_firefox-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dc4a138e950e571ef96391db6b966e12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4951,
"upload_time": "2023-05-23T13:35:27",
"upload_time_iso_8601": "2023-05-23T13:35:27.189243Z",
"url": "https://files.pythonhosted.org/packages/05/8c/260cafb074cedab0b6aaec4d55433971773fd8cb21d4dba78abd1652ced5/dotbot_firefox-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-23 13:35:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kurtmckee",
"github_project": "dotbot-firefox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dotbot-firefox"
}
JSON
