{"id":17648081,"url":"https://github.com/kiran94/dotfiles-sync","last_synced_at":"2025-07-12T03:42:55.296Z","repository":{"id":57423714,"uuid":"322868805","full_name":"kiran94/dotfiles-sync","owner":"kiran94","description":"Manages dotfile configuration files across operating systems","archived":false,"fork":false,"pushed_at":"2021-04-03T20:21:05.000Z","size":58,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-11T12:12:15.508Z","etag":null,"topics":["dotfiles","environments"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/dotfiles-sync/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiran94.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-19T14:43:12.000Z","updated_at":"2023-08-28T14:35:20.000Z","dependencies_parsed_at":"2022-08-29T22:52:04.485Z","dependency_job_id":null,"html_url":"https://github.com/kiran94/dotfiles-sync","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/kiran94/dotfiles-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fdotfiles-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fdotfiles-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fdotfiles-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fdotfiles-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiran94","download_url":"https://codeload.github.com/kiran94/dotfiles-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiran94%2Fdotfiles-sync/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264932785,"owners_count":23685284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotfiles","environments"],"created_at":"2024-10-23T11:16:13.076Z","updated_at":"2025-07-12T03:42:55.260Z","avatar_url":"https://github.com/kiran94.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotfiles-sync\n\n![Deploy](https://github.com/kiran94/dotfiles-sync/workflows/Deploy/badge.svg) ![pypi](https://img.shields.io/pypi/v/dotfiles-sync?color=blue\u0026style=flat-square)\n\ndotfiles-sync is a command line application which helps manage configuration files (typically dotfiles) across different machines and operating systems. \n\n- [dotfiles-sync](#dotfiles-sync)\n  - [Motivation](#motivation)\n  - [Getting Started](#getting-started)\n    - [`list`](#list)\n    - [`sync`](#sync)\n    - [`update`](#update)\n    - [Other](#other)\n      - [Disabling Items](#disabling-items)\n      - [Filtering Items](#filtering-items)\n    - [Environment Variables](#environment-variables)\n\n## Motivation\n\nI needed a solution which would allowed me to easily automate synchronising my configuration files as I jump between different machines which could be either Windows or Linux.\n\n## Getting Started\n\nThis package is deployed to [pypi](https://pypi.org/project/dotfiles-sync/):\n\n```sh\npython -m pip install dotfiles-sync\n```\n\n\nThe `--help` will always show the most up to date options:\n\n```sh\n❯ dotfiles --help\nusage: dotfiles [-h] [-c CONFIG] [-w CONFIG_DIR] [-d] [-i] [-f FILTER [FILTER ...]] [--version] {list,sync,update} ...\n\npositional arguments:\n  {list,sync,update}\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        dotfiles configuration. Points to target locations.\n  -w CONFIG_DIR, --config_dir CONFIG_DIR\n                        Location of the configuration files to sync\n  -d, --dry             Only read and show me what you would have done\n  -i, --interactive     Before doing a write, ask for confirmation\n  -f FILTER [FILTER ...], --filter FILTER [FILTER ...]\n                        keys(s) of the configuration to apply. If not set then apply them all\n  --version             show program's version number and exit\n```\n\nThis application relies on the fact that you store your configuration in source control and that you define a configuration file which declares your configurations you want to track along with paths per operating system. \n\nAn example of a configuration file is:\n\n```sh\n{\n    \"config\": \n    {\n        \".bashrc\": \n        {\n            \"linux\": \"~/.bashrc\",\n            \"windows\": \"~/.bashrc\"\n        }\n    }\n}\n```\n\nTypically named `dotfiles-sync.json`, this file defines each of the configurations we are interested in along with the locations where they should live per operating system. In this example we have a single entry `.bashrc` which states that we have a file in the root of the *configuration directory* with the same name. The *configuration directory* is the directory where the central authority of that files live (typically a git repository which contains all your configuration files).\n\nThis entry can also be a folder or file within a subdirectory (e.g `bash/.bashrc`) for if you wanted to keep all your bash related configuration files organised into a `bash` folder in your repo.\n\nEach entry contains paths to operating system specific path the file should be syncronised into. The operating systems supported here are the same as the ones that come in [platform.system](https://docs.python.org/3/library/platform.html#platform.system) but lowercased. Paths are also expanded using [os.path.expanduser](https://docs.python.org/3/library/os.path.html#os.path.expanduser) which means special symbols like `~` will be expanded in both Window and Linux.\n\n**Note if you have a path which can be applied across platforms, then you can define a single config `\"cross\": \"~/.bashrc\"`.**\n\n### `list`\n\nOnce you have a dotfiles configuration and configuration directory you can run `list`:\n\n```sh\n❯ dotfiles --config examples/dotfiles-sync.json --config_dir examples/configs list\n[18:58:55] INFO     Listing Configurations\n           INFO     .bashrc: examples/configs/.bashrc =\u003e /home/kiran/.bashrc (ConfigurationMatchStatus.SYNCHRONIZABLE | ConfigurationFileType.FILE)\n           INFO     .vimrc: examples/configs/.vimrc =\u003e /home/kiran/.vimrc (ConfigurationMatchStatus.SYNCHRONIZABLE | ConfigurationFileType.FILE)\n           INFO     pgcli: examples/configs/pgcli =\u003e /home/kiran/.config/pgcli (ConfigurationMatchStatus.SYNCHRONIZABLE | ConfigurationFileType.DIRECTORY)\n```\n\n`SYNCHRONIZABLE` means it looks like it is possible to synchronise this file and `FILE` tells us the type of synchronize it's going to do (as oppsosed to `DIRECTORY` which will do a recursive copy).\n\n### `sync`\n\nIf we are happy, then we can do a `sync`. This will take the files in your configuration directory and allow them to the machine.\n\n```sh\n❯ dotfiles --config examples/dotfiles-sync.json --config_dir examples/configs sync\n\n[18:59:41] INFO     Copying File examples/configs/.bashrc =\u003e /home/kiran/.bashrc\n           INFO     Copying File examples/configs/.vimrc =\u003e /home/kiran/.vimrc\n           INFO     Copying Directory examples/configs/pgcli =\u003e /home/kiran/.config/pgcli\nSyncing Configuration... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00\n```\n\n### `update`\n\nYou may want to also do the reverse and update your configuration directory with the files on your current machine. This can be done using `update`:\n\n```sh\n❯ dotfiles --config examples/dotfiles-sync.json --config_dir examples/configs update\n\n[19:01:47] INFO     Copying File /home/kiran/.bashrc =\u003e examples/configs/.bashrc\n           INFO     Copying File /home/kiran/.vimrc =\u003e examples/configs/.vimrc\n           INFO     Copying Directory /home/kiran/.config/pgcli =\u003e examples/configs/pgcli\nUpdating Configuration Directory: examples/configs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00\n```\n\n### Other\n\n#### Disabling Items\n\nConfiguration Items can be disabled from being applied within the config file.\n\n```json\n{\n  \"config\":\n  {\n    \"zsh/.p10k.zsh\": \n    {\n            \"linux\": \"~/.p10k.zsh\",\n            \"disabled\": true\n    }\n  }\n}\n```\n\n#### Filtering Items\n\nBy default dotfiles will assume you want to run configuration on all items (unless explictely `disabled`). If you would like to only apply certain configurations then you can pass the keys of the configs you want to `--filter`:\n\n```sh\n❯ dotfiles -c $HOME/projects/dotfiles/dotfiles-sync.json  --filter \"bash/.profile\" \"pgcli/config\" -w $HOME/projects/dotfiles/ sync\n\n[14:54:59] INFO     Copying File /home/kiran/projects/dotfiles/bash/.profile =\u003e /home/kiran/.profile                                                                                                                \n           INFO     Copying File /home/kiran/projects/dotfiles/pgcli/config =\u003e /home/kiran/.config/pgcli/config                                                                                                     \nSyncing Configuration... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00\n```\n\n### Environment Variables\n\nIt can be cumbersome to type out / remember where your dotfiles directory is on each machine. There are two environment variables to make life easier which you can set on a system level:\n\n```sh\nexport DOTFILESSYNC_CONFIG= # path to the dotfiles-sync.json\nexport DOTFILESSYNC_DIR= # path to your dotfiles which should be synced\n```\n\nThis means makes invocation of this dotfiles-sync much cleaner:\n\n```sh\ndotfiles sync\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiran94%2Fdotfiles-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiran94%2Fdotfiles-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiran94%2Fdotfiles-sync/lists"}