{
    "info": {
        "author": "Olaf Conradi",
        "author_email": "olaf@conradi.org",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Environment :: Console",
            "Intended Audience :: End Users/Desktop",
            "License :: OSI Approved :: BSD License",
            "Operating System :: POSIX",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3.8",
            "Topic :: Software Development :: Version Control",
            "Topic :: System :: Shells",
            "Topic :: System :: Systems Administration",
            "Topic :: Utilities"
        ],
        "description": "\nDotSecrets\n==========\n\nDotSecrets [1]_ is a tool written by Olaf Conradi to facilitate storing\nyour dotfiles in Git, including those with private information.\n\nBy storing your configuration files in a public Git repository, you can\nsynchronize your settings between multiple devices or share them with\nothers. Any private information is kept in a single file store outside\nthe repository. It's up to the user to transport this file between devices.\n\nThis tool is similar in functionality to Briefcase [2]_ but differs\nsignificantly. DotSecrets uses Git filtering to manage private information\nand uses a different file hierarchy and naming convention.\n\nFor more information on the filtering capabilities of Git, see the\ngit attributes manual [3]_ in section Effects under filter attribute.\n\nSymbolic linking and unlinking is supported by organizing your dotfiles in\ntopics (specific topic names as top level directory within your repository).\nThe stow and unstow commands automate linking and unlinking them. You decide\nhow to name your topics. Either by application or device name, or a\ncombination of the two. This practise is explained in a blog article [4]_ by\nBrandon Invergo back in 2012.\n\n\nDependencies\n------------\n\nDotSecrets depends on ruamel.yaml [5]_ for reading configuration files and\ndploy [6]_ for stow functionality.\n\n\nInstallation\n------------\n\nRun::\n\n    $ pip3 install dotsecrets\n\nYou should then have a ``dotsecrets`` script available in a new shell.\n\nWhen installing directly from the Git repository [1]_ use::\n\n    $ pip3 install .\n\nYou might need to symlink it into your ``~/bin`` folder::\n\n    $ ln -s ~/.local/bin/dotsecrets ~/bin\n\n\nUsage\n-----\n\nDotSecrets is to be used together with Git to manage your dotfiles.\n\nGit filters are used to clean and smudge secrets. Each filter is configured\nusing regular expressions grouped per filter name. The filters are named\nafter the file path relative to the Git root directory.\n\n\nFilters\n-------\n\nFilter rules are defined in a file called ``.dotfilters.yaml`` inside the\ndotfiles repository.\n\nIts syntax is as follows:\n\n.. code-block:: yaml\n\n    version: 2\n    filters:\n      \"mutt/.mutt/muttrc\":\n        rules:\n          passwd:\n            description: Mutt passwords\n            numbered: true\n            regex: password(\\s*)=(\\s*)(?#WSUpToHash)\n            substitute: password\\1=\\2(?#Key)\n      \"irssi/.irssi/config\":\n        encoding: latin1\n        rules:\n          nickname:\n            description: IRC nickname\n            regex: nick(\\s*)=(\\s*)(?#QuotedString);\n            substitute: nick\\1=\\2\"(?#Key)\";\n          realname:\n            regex: real_name(\\s*)=(\\s*)(?#QuotedString);\n            substitute: real_name\\1=\\2\"(?#Key)\";\n\nThis file contains filter rules for each file that contains secrets. The\nfirst example defines a filter for replacing passwords in mutt configuration\nfiles. A secret is detected by a regular expression matching on each line\ncontaining the word ``password`` followed by an equal sign and each character\n(except whitespace) up to an optional hash ``#`` comment.\n\nA match is replaced by the following: ``password = $DotSecrets: password_1$``.\nThe key is appended with the number of matches because ``numbered`` is defined\nas ``true``. This allows for multiple matches and substitutions as long as the\nordering in the file is retained.\n\nThe second example shows a filter for hiding your nickname in an Irssi\nconfiguration file. The encoding field will make sure the file is opened\nin the specified encoding (default encoding is utf-8). The regular expression\nmatches any line containing the word nick followed by whitespace and one or\nmore alphanumeric characters. A match is replaced by\n``nick = \"$DotSecrets: nickname$\";``.\n\nSimilar for the filter to hide your real name in the same file. The regular\nexpression matches any line containing ``real_name`` followed by an equal\nsign, quoted text and a final semi-colon. A match is replaced by\n``real_name = \"$DotSecrets: realname$\";``.\n\nPlease note that the description, numbered and encoding fields are optional.\n\nThe regular expressions and substitutions follow the Python regular expression\nsyntax [7]_. Substitutions can reference regex groups ``(...)`` using\n``\\number`` syntax. To make it easier to define complex regular expressions,\nthe following shortcuts are available. They are defined as regex comments\n``(?#...)``:\n\n======================  ====================================================\nShortcut                Description\n======================  ====================================================\n(?#QuotedString)        Matches balanced single or double quoted strings and\n                        is able to cope with escaped quote symbols within\n                        the string\n(?#QuotedOrSingleWord)  Same as QuotedString or an unquoted single word of\n                        non-whitespace characters\n(?#WSUpToHash)          Matches whitespace up to the hash symbol ``#``\n(?#WSUpToSemicolon)     Matches whitespace up to the semi colon symbol ``;``\n(?#Key)                 Used to substitute the secret\n======================  ====================================================\n\n\nSecrets\n-------\n\nSecret information, like passwords, answers to security questions, and other\nsensitive information is stored in a file called ``dotsecrets.yaml`` inside\nthe XDG configuration directory (typically\n``~/.config/dotsecrets/dotsecrets.yaml``).\n\nIts syntax is as follows:\n\n.. code-block:: yaml\n\n    version: 2\n    filters:\n      \"mutt/.mutt/muttrc\":\n        secrets:\n          password_1:\n            description: Password for GMail\n            secret: s3cr3t\n          password_2:\n            description: Password for Hotmail\n            secret: f00bar\n      \"irssi/.irssi/config\":\n        secrets:\n          nick:\n            secret: mynick\n          realname:\n            secret: My Real Name\n\nThis configuration file contains two filters for mutt and irssi. Each\nfilter contains one or more secrets. These secrets are used to filter the\nfiles in the Git repository for sensitive data. Each secret has an optional\ndescription field.\n\n\nLinking filters and secrets\n---------------------------\n\nGit attributes are used to link file patterns to Git filters. The filters are\ndefined in git config files.\n\nContents of ``.gitattributes``::\n\n    * filter=dotsecrets\n\nWhen checking in files with Git, the clean command is run for those files that\nmatch the pattern given in ``.gitattributes``. When checking out files that\nhave a filter defined, the smudge command substitutes the secrets again.\n\nTo add these filters run the following commands::\n\n    $ git config filter.dotsecrets.clean \"dotsecrets clean %f\"\n    $ git config filter.dotsecrets.smudge \"dotsecrets smudge %f\"\n    $ git config filter.dotsecrets.required true\n\nThey result in the following addition to your ``.git/config`` file:\n\n.. code-block:: ini\n\n    [filter \"dotsecrets\"]\n        clean = dotsecrets clean %f\n        smudge = dotsecrets smudge %f\n        required = true\n\nUpon filtering (typically on git checkin, checkout or diff) the ``%f``\nargument is replaced by the file path relative to the Git root directory.\nThis is why filters must be named accordingly.\n\n\nInitialize Repository\n---------------------\n\nUpon a fresh checkout of the dotfiles repository, the git filter and git\nattributes configuration are not yet in place. The ``init`` command is\navailable to initialize the configuration (when needed) and do the initial\nsmudge on files defined as having secrets.\n\nExample::\n\n    $ git clone git@github.com:username/dotfiles.git\n    $ cd dotfiles\n    $ dotsecrets init\n\n\nStow and Unstow\n---------------\n\nUsing the stow command each topic is linked into your home directory. The\nunstow command will unlink them. The topics to act upon are specified\non the command line. To act on all available topics pass the ``--all``\nargument. Add ``--dry-run`` to simulate which actions will be taken\nwithout doing them.\n\nTo stow and unstow the current working directory must be set inside the\ndotfilters repository.\n\nExample::\n\n    $ dotsecrets stow mutt irssi\n\nThis will stow both topics.\n\nUse the following to simulate the actions for linking mutt. The output\nis a list of actions needed::\n\n    $ dotsecrets stow --dry-run mutt\n    dploy stow: link /home/user/.mutt => dotfiles/mutt/.mutt\n\n\nTo remove the symbolic links from your home directory, run::\n\n    $ dotsecrets unstow --dry-run mutt\n    dploy stow: unlink /home/user/.mutt => dotfiles/mutt/.mutt\n\n\nAdding new dotfiles\n-------------------\n\nDefining regular expressions for new filters might require some practise.\nTo test your filter definitions a ``test`` command is available::\n\n    $ dotsecrets test irssi/.irssi/config\n    --- /home/olaf/src/dotfiles/irssi/.irssi/config 2019-07-15 22:40:03.782600150 +0200\n    +++ /home/olaf/src/dotfiles/irssi/.irssi/config.dotclean        2019-07-17 21:23:22.813039617 +0200\n    @@ -286,8 +286,8 @@\n\n     settings = {\n       core = {\n    -    real_name = \"My Real Name\";\n    -    nick = \"mynick\";\n    +    real_name = \"$DotSecrets: realname$\";\n    +    nick = \"$DotSecrets: nick$\";\n       };\n       \"fe-text\" = { actlist_sort = \"refnum\"; scrollback_lines = \"2000\"; };\n       \"fe-common/core\" = {\n\nTwo intermediate files are created: ``config.dotclean`` and\n``config.dotsmudge``. The difference is shown between the original source\n(which contains secrets) and the cleaned up file (which will contain\nmarkers). Next, the cleaned source is smudged to replace the markers with the\nsecrets from your secrets store. The resulting file should be identical to\nthe original source file. If that is not the case, the difference is shown.\n\nSuppose a typo was made in the secrets store::\n\n    $ dotsecrets test irssi/.irssi/config\n    --- /home/olaf/src/dotfiles/irssi/.irssi/config 2019-07-15 22:40:03.782600150 +0200\n    +++ /home/olaf/src/dotfiles/irssi/.irssi/config.dotclean        2019-07-17 21:23:22.813039617 +0200\n    @@ -286,8 +286,8 @@\n\n     settings = {\n       core = {\n    -    real_name = \"My Real Name\";\n    -    nick = \"mynick\";\n    +    real_name = \"$DotSecrets: realname$\";\n    +    nick = \"$DotSecrets: nick$\";\n       };\n       \"fe-text\" = { actlist_sort = \"refnum\"; scrollback_lines = \"2000\"; };\n       \"fe-common/core\" = {\n    --- /home/olaf/src/dotfiles/irssi/.irssi/config 2019-07-17 21:27:21.118130339 +0200\n    +++ /home/olaf/src/dotfiles/irssi/.irssi/config.dotsmudge       2019-07-17 21:36:48.327586627 +0200\n    @@ -287,7 +287,7 @@\n     settings = {\n       core = {\n         real_name = \"My Real Name\";\n    -    nick = \"mynick\";\n    +    nick = \"myname\";\n       };\n       \"fe-text\" = { actlist_sort = \"refnum\"; scrollback_lines = \"2000\"; };\n       \"fe-common/core\" = {\n    Source '/home/olaf/src/dotfiles/irssi/.irssi/config' and smudged source differ\n    Please adjust filter definition or validate your stored secrets\n\nIn the example above, key nick was set to myname not mynick in the secrets\nstore. When the execution finishes, the intermediate files are deleted. If\nyou want to retain those files for closer inspection, specify the ``--keep``\nflag on the command line.\n\nWhen you are satisfied with the output you can add the original source under\nversion control. The clean filter will be applied before the commit.\n\n\nReferences\n==========\n\n.. [1] https://github.com/oohlaf/dotsecrets\n.. [2] https://github.com/jim/briefcase\n.. [3] https://git-scm.com/docs/gitattributes\n.. [4] http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html\n.. [5] https://pypi.org/project/ruamel.yaml\n.. [6] https://pypi.org/project/dploy\n.. [7] https://docs.python.org/3/library/re.html#regular-expression-syntax\n\n\nChanges\n=======\n\n0.3.1 (2019-07-25)\n------------------\n- Testing on PyPI resulted in stricter dependencies\n\n0.3 (2019-07-25)\n----------------\n- Code changed to Python 3 only\n- Based filters on file names which simplifies config a lot\n- Breaking change in YAML file config format\n- Breaking change in git filter config (one config to rule all secrets)\n- Changed YAML parser to ruamel.yaml\n- Added stow and unstow command to manage linking of dotfiles\n- Added test command to simplify adding new dotfiles\n\n0.2 (2017-08-30)\n----------------\n- Make code compatible with Python 3\n\n0.1 (2016-07-03)\n----------------\n- Add console script\n- Code clean up, fix pylint warnings\n\n0.0 (2013-05-11)\n----------------\n- Initial version\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/oohlaf/dotsecrets",
        "keywords": "manage dotfiles git stow secret private password",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "dotsecrets",
        "package_url": "https://pypi.org/project/dotsecrets/",
        "platform": "",
        "project_url": "https://pypi.org/project/dotsecrets/",
        "project_urls": {
            "Bug Reports": "https://github.com/oohlaf/dotsecrets/issues",
            "Homepage": "https://github.com/oohlaf/dotsecrets"
        },
        "release_url": "https://pypi.org/project/dotsecrets/0.3.1/",
        "requires_dist": [
            "ruamel.yaml (>=0.15.100)",
            "dploy (>=0.1.2)"
        ],
        "requires_python": ">=3.7",
        "summary": "DotSecrets is a tool to facilitate storing your dotfiles in Git, including those with private information. The private information is filtered before committing to the repository. DotSecrets is able to symlink your dotfiles into your home directory.",
        "version": "0.3.1"
    },
    "last_serial": 5585241,
    "releases": {
        "0.3.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "2c5fe0fb430eb646f491955c00c4ebc5",
                    "sha256": "2a07be13fc0158b36ce3d38bddd3deac9ed2f6b277d9a31219ba7d3be77dddf5"
                },
                "downloads": -1,
                "filename": "dotsecrets-0.3.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "2c5fe0fb430eb646f491955c00c4ebc5",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": ">=3.7",
                "size": 18185,
                "upload_time": "2019-07-25T19:26:15",
                "url": "https://files.pythonhosted.org/packages/4c/a3/9fcdd7543005b16aec5f4115502dda4be1fa40ebe37f210d6d1af69df534/dotsecrets-0.3.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "a6f0e1a48e49277fe4f81732b440f193",
                    "sha256": "e490c9695fe335490468cca73286e79be5913f735f641ea862dc1e0bed3c3746"
                },
                "downloads": -1,
                "filename": "dotsecrets-0.3.1.tar.gz",
                "has_sig": false,
                "md5_digest": "a6f0e1a48e49277fe4f81732b440f193",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.7",
                "size": 18271,
                "upload_time": "2019-07-25T19:26:18",
                "url": "https://files.pythonhosted.org/packages/9e/b8/d40e3dd45231b82d308b3786568a6d46283c031504faa7c26429d974f28b/dotsecrets-0.3.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "2c5fe0fb430eb646f491955c00c4ebc5",
                "sha256": "2a07be13fc0158b36ce3d38bddd3deac9ed2f6b277d9a31219ba7d3be77dddf5"
            },
            "downloads": -1,
            "filename": "dotsecrets-0.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2c5fe0fb430eb646f491955c00c4ebc5",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 18185,
            "upload_time": "2019-07-25T19:26:15",
            "url": "https://files.pythonhosted.org/packages/4c/a3/9fcdd7543005b16aec5f4115502dda4be1fa40ebe37f210d6d1af69df534/dotsecrets-0.3.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "a6f0e1a48e49277fe4f81732b440f193",
                "sha256": "e490c9695fe335490468cca73286e79be5913f735f641ea862dc1e0bed3c3746"
            },
            "downloads": -1,
            "filename": "dotsecrets-0.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "a6f0e1a48e49277fe4f81732b440f193",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 18271,
            "upload_time": "2019-07-25T19:26:18",
            "url": "https://files.pythonhosted.org/packages/9e/b8/d40e3dd45231b82d308b3786568a6d46283c031504faa7c26429d974f28b/dotsecrets-0.3.1.tar.gz"
        }
    ]
}