{"id":15717951,"url":"https://github.com/snakypy/dotctrl","last_synced_at":"2025-10-08T18:15:41.770Z","repository":{"id":45096499,"uuid":"249577975","full_name":"snakypy/dotctrl","owner":"snakypy","description":":snake: :package: :page_facing_up: Dotctrl is a package to control your dotfiles (and more) on Linux or macOS.","archived":false,"fork":false,"pushed_at":"2024-09-25T13:05:05.000Z","size":8404,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T08:06:08.414Z","etag":null,"topics":["cli","control","ctrl","dotfiles","dotfiles-manager","linux","macos","macos-app","management","manager","pypi","python","python-3","restore","shell","snakypy","symbolic-links"],"latest_commit_sha":null,"homepage":"","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/snakypy.png","metadata":{"files":{"readme":".github/readme/pt_BR.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-03-24T00:50:40.000Z","updated_at":"2024-12-30T22:24:56.000Z","dependencies_parsed_at":"2024-10-24T14:31:28.167Z","dependency_job_id":"214c62c9-44f4-4d07-b65d-951249600690","html_url":"https://github.com/snakypy/dotctrl","commit_stats":{"total_commits":462,"total_committers":1,"mean_commits":462.0,"dds":0.0,"last_synced_commit":"bf9c25bc6118f02e817ac573f5f8aaa361181283"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakypy%2Fdotctrl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakypy%2Fdotctrl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakypy%2Fdotctrl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakypy%2Fdotctrl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snakypy","download_url":"https://codeload.github.com/snakypy/dotctrl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251790213,"owners_count":21644182,"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":["cli","control","ctrl","dotfiles","dotfiles-manager","linux","macos","macos-app","management","manager","pypi","python","python-3","restore","shell","snakypy","symbolic-links"],"created_at":"2024-10-03T21:51:44.466Z","updated_at":"2025-10-08T18:15:36.746Z","avatar_url":"https://github.com/snakypy.png","language":"Python","readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://github.com/snakypy/dotctrl\"\u003e\n    \u003cimg alt=\"Dotctrl\" src=\"https://raw.githubusercontent.com/snakypy/assets/main/dotctrl/images/dotctrl-transparent.png\" width=\"auto\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003ch1 align=\"center\"\u003e A ferramenta de controle de \"dotfiles\". \u003c/h1\u003e\n\n[![Tests](https://github.com/snakypy/dotctrl/workflows/Tests/badge.svg)](https://github.com/snakypy/dotctrl/actions)\n[![Python Versions](https://img.shields.io/pypi/pyversions/dotctrl)](https://pyup.io/repos/github/snakypy/dotctrl/)\n[![Updates](https://pyup.io/repos/github/snakypy/dotctrl/shield.svg)](https://pyup.io/repos/github/snakypy/dotctrl/)\n[![Python Whell](https://img.shields.io/pypi/wheel/dotctrl)](https://pypi.org/project/wheel/)\n[![PyPI](https://img.shields.io/pypi/v/dotctrl)](https://pypi.org/project/dotctrl/#history)\n[![PyPI - Implementation](https://img.shields.io/pypi/implementation/dotctrl)](https://pypi.org/project/dotctrl)\n[![Isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n[![Mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)\n[![Code style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/dotctrl)](https://pypi.org/project/dotctrl/#files)\n[![GitHub license](https://img.shields.io/github/license/snakypy/dotctrl)](https://github.com/snakypy/dotctrl/blob/main/LICENSE)\n\n----------------\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eConstruído com ❤︎ por:\n  \u003ca href=\"https://williamcanin.github.io\" target=\"_blank\"\u003eWilliam Canin\u003c/a\u003e no tempo livre,\n   ao som da playlist: \u003ca href=\"https://open.spotify.com/playlist/48brJJZdVifY79QAFmEImq?si=GmsvfKqATpG4p72ZeVClIQ\" target=\"_blank\"\u003eBursting Of The Tympanum\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cdiv class=\"sumary\"\u003e\n  \u003ch1\u003e Sumário \u003c/h1\u003e\n  \u003cul\u003e\n      \u003cli\u003e\n          \u003ca href=\"#sobre\"\u003eSobre\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#características\"\u003eCaracterísticas\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#requisitos\"\u003eRequisitos\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#instalando\"\u003eInstalando\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#usando\"\u003eUsando\u003c/a\u003e\n          \u003cul\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#init\"\u003einit\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#pull\"\u003epull\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#link\"\u003elink\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#unlink\"\u003eunlink\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#restore\"\u003erestore\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#repo\"\u003erepo\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#find\"\u003efind\u003c/a\u003e\n              \u003c/li\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#config\"\u003econfig\u003c/a\u003e\n              \u003c/li\u003e\n          \u003c/ul\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#flags-globais\"\u003eFlags Globais\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#arquivo-de-configuração-dotctrljson\"\u003eArquivo de configuração (dotctrl.json)\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#variável-de-ambiente\"\u003eVariável de ambiente\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#atualizando\"\u003eAtualizando\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#mais-comandos\"\u003eMais Comandos\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#extras\"\u003eExtras\u003c/a\u003e\n          \u003cul\u003e\n              \u003cli\u003e\n                  \u003ca href=\"#deploy-e-clone-do-repositório-dotctrl\"\u003eDeploy e Clone do repositório Dotctrl\u003c/a\u003e\n              \u003c/li\u003e\n          \u003c/ul\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#doação\"\u003eDoação\u003c/a\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n          \u003ca href=\"#licença\"\u003eLicença\u003c/a\u003e\n      \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/div\u003e\n\n# Sobre\n\nInicialmente, o **Dotctrl** surgiu apenas para controlar \"aquivos dotfiles\", porem, ao decorrer, ele se tornou mais do que isso.\nAgora, o **Dotctrl** é um mantenedor de qualquer tipo arquivo e pasta dentro do seu próprio repositório particular.\n\nIsso é demais!\n\nO **Dotctrl** irá gerenciar os elementos do diretório HOME do usuário; funcionando em cima de um arquivo de configuração (`dotctrl.json`) que contém os caminhos do local de origem dos elementos.\n\nTodos os elementos gerenciados pelo **Dotctrl** são mantidos no repositório/pasta \"**dotctrl**\".\n\n\nVeja uma demonstração:\n\n![](https://raw.githubusercontent.com/snakypy/assets/main/dotctrl/gifs/demo.gif)\n\n# Características\n\n* Suporta aos idiomas: Inglês Americano e Português brasileiro;\n* Crie (ou não) vários repositórios para seus elementos;\n* Abandone a criação de links simbólicos manuais enormes;\n* O repositório armazena a mesma estrutura de caminho que seu local (`$HOME`) original;\n* Gerencie elementos únicos ou em massa;\n* Restaure os elementos do repositório para sua localização original com um único comando;\n* E muito mais :)\n\n# Requisitos\n\nPara funcionar corretamente, você precisará primeiro:\n\n- [`Linux`](https://www.kernel.org) ou [`macOS`](https://www.apple.com/macos)\n- [`Python`](https://python.org) (v3.9 ou recente);\n- [`Pip`](https://pip.pypa.io/en/stable/) (v19.3 ou recente) deve ser instalado;\n- [`Git`](https://git-scm.com/downloads) (v2.0 ou recente);\n- Um desse editor [vim](https://www.vim.org/), [nano](https://www.nano-editor.org/), [emacs](https://www.gnu.org/software/emacs/) ou [micro](https://micro-editor.github.io/) devem ser instalado;\n\n\n# Instalando\n\nÉ hora de instalar o **Dotctrl**. Para fazer isso, faça:\n\n```shell\npython3 -m pip install dotctrl --user\n```\n\n\u003e NOTA: Se você estiver instalando no ambiente local do usuário, certifique-se de adicionar as variáveis de ambiente ao arquivo `zshrc`\n\u003e ou arquivo `.bashrc`.\n\n# Usando\n\n## init\n\nApós instalar o pacote, você precisa criar o repositório **Dotctrl** em uma pasta vazia no local do sua\nescolha. Recomendamos sempre criar no diretório raiz **/home** ou **/Users**, pois criando na pasta do usuário, pode ser\nperdido se o usuário for excluído. Com isso, veja o exemplo abaixo:\n\nLinux:\n\n```shell\nsudo mkdir -p /home/.dotfiles; cd $_\nsudo chown -R $(whoami) /home/.dotfiles\nsudo chmod -R 700 /home/.dotfiles\ndotctrl init\n```\n\nmacOS:\n\n```shell\nsudo mkdir -p /Users/.dotfiles; cd $_\nsudo chown -R $(id -un) /Users/.dotfiles\nsudo chmod -R 700 /Users/.dotfiles\ndotctrl init\n```\n\n### --auto\n\nVocê pode contornar todos esses comandos acima usando a flag `--auto`. O **Dotctrl** criará automaticamente uma base\ndiretório para armazenar os dados, no entanto, você **DEVE** ter permissão sudo.\n\n\u003e Recomendamos usar fortemente está opção caso tenha permissão.\n\n```shell\ndotctrl init --auto\n```\n\n### --git\n\nEsta flag faz com que o **Dotctrl** crie um repositório [git](https://git-scm.com) dentro do repositório **Dotctrl**.\n\n```shell\ndotctrl init --git\n```\n\nVocê também pode combinar está flag com a flag [`--auto`](#--auto):\n\n```shell\ndotctrl init --auto --git\n```\n\n## pull\n\nCom a base já criada, é hora de você PUXAR os elementos para a base do **Dotctrl** com o comando `pull`.\n\nPuxe **UM** [elemento]() para o repositório **Dotctrl**:\n\n```shell\ndotctrl pull --e .zprofile\n```\n\nSe você quiser fazer um **pull** massivo, faça:\n\n```shell\ndotctrl pull\n```\n\n\u003e Nota: Esta opção só é possível se você passar os [elements](#section-elements) manualmente no arquivo **dotctrl.json** ou não ter limpadado o [registro](#autoclean).\n\n\n## link\n\nDepois de puxar o(s) elemento(s), crie links simbólicos para eles em seus locais originais:\n\n```shell\ndotctrl link --e .zprofile\n```\n\nSe você quiser realizar um **link** massivo, faça:\n\n```shell\ndotctrl link\n```\n\n\u003e Nota: Esta opção só é possível se você passar os [elements](#section-elements) manualmente no arquivo **dotctrl.json** ou não ter limpado o [registro](#autoclean).\n\n## unlink\n\nDesvincule o elemento do repositório com o local de origem:\n\n```shell\ndotctrl unlink --e .zprofile\n```\n\nSe você quiser **desvincular** elementos de forma massiva, faça:\n\n```shell\ndotctrl unlink\n```\n\n\u003e Nota: Esta opção só é possível se você passar os [elements](#section-elements) manualmente no arquivo **dotctrl.json** ou não ter limpadado o [registro](#autoclean).\n\n## restore\n\nEste comando irá tirar um elemento do repositório **Dotctrl** e restaurar para seu local original:\n\n```shell\ndotctrl restore --e .zprofile\n```\n\nSe você quiser realizar uma **restauração** massiva, faça:\n\n```shell\ndotctrl restore\n```\n\n\u003e Nota: Por padrão, ao restaurar elemento(s) para o local de origem, o **Dotctrl** NÃO remove os elemento do registro\n\u003e (`dotctrl.json`). Para limpar, veja [--autoclean](#autoclean).\n\n## repo\n\nEste comando trás informações do repositório, veja abaixo alguns de seu subcomandos:\n\n### --check\n\nFaça uma verificação para ver se há elementos a serem vinculados:\n\n```shell\ndotctrl repo --check\n```\n\n### --ls\n\nVerifique os elementos já importados no repositório do **Dotctrl**.\n\n```shell\ndotctrl repo --ls\n```\n\n### --info\n\nCom o comando abaixo você pode ver algumas informações do repositório **Dotctrl**, como quantidade de pastas e arquivos,\no caminho absoluto do repositório e se a variável de ambiente `DOTCTRL_PATH` estiver ativa.\n\n```shell\ndotctrl repo --info\n```\n\n## find\n\nPesquisa qualquer elemento dentro do repositório do **Dotctrl**. Para isso, use o comando:\n\n```shell\ndotctrl find --name .zprofile\n```\n\n\u003e Nota: Envolva o elemento a ser encontrar com aspas duplas caso o mesmo tenha espaços no nome.\n\n## config\n\nEste comando irá manipular o arquivo de configuração do **Dotctrl**, veja abaixo alguns subcomandos do mesmo.\n\n### --autoclean\n\nFaz uma limpeza nos elementos presentes no arquivo de configuração do **Dotctrl**.\nQualquer elemento que estiver presente no arquivo de configuração do **Dotctrl** e não EXISTIR no repositório, serão eliminados do arquivo de configuração.\n\nGeralmente o `--autoclean` é usado após usar o comando de [restauração](#restore) de elementos.\n\n```shell\ndotctrl config --autoclean\n```\n\n### --view\n\nDê uma espiada no arquivo de configuração do **Dotctrl** pelo terminal.\n\n### --open\n\nPermite editar o arquivo de configuração do **Dotctrl** no próprio terminal usando o comando:\n\n```shel\ndotctrl config --open\n```\n\n\u003e Nota: Usa por padrão o editor `vim`, caso não tenha, irá tentar usar o `nano`, `emacs` ou `micro`.\n\n### --lang\n\nUse está flag para alterar o idioma do **Dotctrl**. No momento, o **Dotctrl** dá suporte para 2 (dois) idiomas, eles são: **Inglês Americano** e **Português Brasileiro**. Ao usar o comando abaixo, irá mostrar uma lista para você escolher qual idioma quer usar. A alteração é instantânea.\n\n```shel\ndotctrl config --lang\n```\n\n## Flags globais\n\n### --e (--element)\n\nA flag **--e** ou **--element**, é responsável por manipular um elemento especifico do repositório **Dotctrl**.\n\nEsta flag deve receber um elemento sem o caminho absoluto, apenas o relativo a partir da `$HOME`.\n\nExemplos:\n\n* `dotctrl pull --e .zprofile`\n* `dotctrl link --e .zprofile`\n* `dotctrl unlink --e .zprofile`\n* `dotctrl restore --e .zprofile`\n\nSe o elemento tiver espaços no nome, envolva-o entre aspas duplas. Exemplo: `dotctrl pull --e \"arquivo legal.txt\"`\n\n### --f (--force)\n\nA flag **--f** ou **--force**, força literalmente o uso do comando, impedindo que algo impeça sua conclusão. Esta opção está presente em todos os comandos que manipula os elementos, esses comandos são o: `pull`, `link`, `unlink` e `restore`.\n\n\n## Arquivo de configuração (dotctrl.json)\n\nEste é um exemplo de uma estrutura completa do arquivo de configuração (`dotctrl.json`) do **Dotctrl**:\n\n```json\n{\n    \"dotctrl\": {\n        \"config\": {\n            \"editor\": \"vim\",\n            \"language\": \"pt_BR\"\n        },\n        \"elements\": [\n            \".zshrc\",\n            \".config/xfce4/terminal/terminalrc\",\n            \".config/Code/User\",\n            \"Images/Wedding\"\n        ],\n    }\n}\n```\n\n## Variável de ambiente\n\nPor padrão, **Dotctrl** funciona com vários diretórios, o que faz com que você precise usá-lo em um determinado diretório que você criou para seus elementos.\n\nSe você quiser usar **Dotctrl** em qualquer PATH, você precisa criar uma variável de ambiente que **Dotctrl** disponibiliza. Esta variável de ambiente é `DOTCTRL_PATH`.\n\nVocê deve inserir a variável `DOTCTRL_PATH` em seu sistema operacional contendo o diretório onde estarão seus dotfiles. Por exemplo, em seu arquivo `.bashrc` ou `.zshrc`:\n\nLinux:\n\n```shell\nexport DOTCTRL_PATH=\"/home/.dotfiles\"\n```\nou\n\nmacOS:\n\n```shell\nexport DOTCTRL_PATH=\"/Users/.dotfiles\"\n```\n\n\u003e NOTA: Lembre-se, ao criar esta variável de ambiente, você não poderá criar outros repositórios para **Dotctrl**.\n\n\n## Atualizando\n\nSe **Dotctrl** tiver novos recursos, atualize a linha de comando abaixo:\n\n```shell\npython3 -m pip install dotctrl -U --user\n```\n\n## Mais comandos\n\nPara obter mais informações de comando, use:\n\n```\ndotctrl [--help | -h]\n```\n\n## Extras\n\n### Deploy e Clone do repositório Dotctrl\n\nAgora que você tem o controle de seus elementos, é hora de fazer o deploy dos mesmo em um serviço de git.\nEste exemplo abaixo mostrará como realizar o deploy e clone no [GitHub](https://github.com).\n\n1 - Deploy:\n\nA - Entrando na pasta raiz criada do **Dotctrl**:\n\nLinux:\n\n```shell\ncd /home/.dotfiles\n```\n\nmacOS:\n\n```shell\ncd /Users/.dotfiles\n```\n\nB - Criando repositório git, commit e salvando (push)\n\n```shell\ngit remote add origin git@github.com:\u003cYOUR USER\u003e/dotfiles.git\ngit init\ngit add .\ngit commit -m \"Update\"\ngit push origin main\n```\n\n2 - Clone:\n\nVocê também pode clonar qualquer diretório de sua escolha, mas vamos manter o diretório de compilação de exemplo acima. Siga os passos:\n\nLinux:\n\n```shell\nsudo mkdir -p /home/.dotfiles\nsudo chmod -R 770 /home/.dotfiles\ncd /home/.dotfiles\ngit clone git@github.com:\u003cYOUR USER\u003e/dotfiles.git .\ndotctrl link --f\n```\n\nmacOS:\n\n```shell\nsudo mkdir -p /Users/.dotfiles\nsudo chmod -R 770 /Users/.dotfiles\ncd /Users/.dotfiles\ngit clone git@github.com:\u003cYOUR USER\u003e/dotfiles.git .\ndotctrl link --f\n```\n\n## Doação\n\nClique na imagem abaixo para ser redirecionado aos formulários de doação:\n\n\u003cdiv class=\"donate\"\u003e\n  \u003ca href=\"https://github.com/snakypy/donations/blob/main/README.md\"\u003e\n    \u003cimg width=\"160\" height=\"100\" src=\"https://raw.githubusercontent.com/snakypy/donations/main/svg/donate/donate-hand.svg\" alt=\"Donations\"/\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\nÉ muito importante você fazer uma doação para motivar a continuação de desenvolvimento do **Dotctrl**. :)\n\n## Licença\n\nO projeto está disponível como código aberto sob os termos da [Licença MIT](https://github.com/snakypy/dotctrl/blob/main/LICENSE) ©\n\n## Creditos\n\nVeja, [AUTHORS](https://github.com/snakypy/dotctrl/blob/main/AUTHORS.rst).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakypy%2Fdotctrl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnakypy%2Fdotctrl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakypy%2Fdotctrl/lists"}