Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/snakypy/dotctrl
:snake: :package: :page_facing_up: Dotctrl is a package to control your dotfiles (and more) on Linux or macOS.
https://github.com/snakypy/dotctrl
cli control ctrl dotfiles dotfiles-manager linux macos macos-app management manager pypi python python-3 restore shell snakypy symbolic-links
Last synced: 4 months ago
JSON representation
:snake: :package: :page_facing_up: Dotctrl is a package to control your dotfiles (and more) on Linux or macOS.
- Host: GitHub
- URL: https://github.com/snakypy/dotctrl
- Owner: snakypy
- License: mit
- Created: 2020-03-24T00:50:40.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-25T13:05:05.000Z (5 months ago)
- Last Synced: 2024-10-25T06:25:20.104Z (4 months ago)
- Topics: cli, control, ctrl, dotfiles, dotfiles-manager, linux, macos, macos-app, management, manager, pypi, python, python-3, restore, shell, snakypy, symbolic-links
- Language: Python
- Homepage:
- Size: 8.01 MB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: .github/readme/pt_BR.md
- Contributing: CONTRIBUTING.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Authors: AUTHORS.rst
Awesome Lists containing this project
README
![]()
A ferramenta de controle de "dotfiles".
[](https://github.com/snakypy/dotctrl/actions)
[](https://pyup.io/repos/github/snakypy/dotctrl/)
[](https://pyup.io/repos/github/snakypy/dotctrl/)
[](https://pypi.org/project/wheel/)
[](https://pypi.org/project/dotctrl/#history)
[](https://pypi.org/project/dotctrl)
[](https://pycqa.github.io/isort/)
[](http://mypy-lang.org/)
[](https://github.com/psf/black)
[](https://pypi.org/project/dotctrl/#files)
[](https://github.com/snakypy/dotctrl/blob/main/LICENSE)----------------
Sumário
Sobre
Características
Requisitos
Instalando
Usando
Flags Globais
Arquivo de configuração (dotctrl.json)
Variável de ambiente
Atualizando
Mais Comandos
Extras
Doação
Licença
# Sobre
Inicialmente, o **Dotctrl** surgiu apenas para controlar "aquivos dotfiles", porem, ao decorrer, ele se tornou mais do que isso.
Agora, o **Dotctrl** é um mantenedor de qualquer tipo arquivo e pasta dentro do seu próprio repositório particular.Isso é demais!
O **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.
Todos os elementos gerenciados pelo **Dotctrl** são mantidos no repositório/pasta "**dotctrl**".
Veja uma demonstração:

# Características
* Suporta aos idiomas: Inglês Americano e Português brasileiro;
* Crie (ou não) vários repositórios para seus elementos;
* Abandone a criação de links simbólicos manuais enormes;
* O repositório armazena a mesma estrutura de caminho que seu local (`$HOME`) original;
* Gerencie elementos únicos ou em massa;
* Restaure os elementos do repositório para sua localização original com um único comando;
* E muito mais :)# Requisitos
Para funcionar corretamente, você precisará primeiro:
- [`Linux`](https://www.kernel.org) ou [`macOS`](https://www.apple.com/macos)
- [`Python`](https://python.org) (v3.9 ou recente);
- [`Pip`](https://pip.pypa.io/en/stable/) (v19.3 ou recente) deve ser instalado;
- [`Git`](https://git-scm.com/downloads) (v2.0 ou recente);
- 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;# Instalando
É hora de instalar o **Dotctrl**. Para fazer isso, faça:
```shell
python3 -m pip install dotctrl --user
```> NOTA: Se você estiver instalando no ambiente local do usuário, certifique-se de adicionar as variáveis de ambiente ao arquivo `zshrc`
> ou arquivo `.bashrc`.# Usando
## init
Após instalar o pacote, você precisa criar o repositório **Dotctrl** em uma pasta vazia no local do sua
escolha. Recomendamos sempre criar no diretório raiz **/home** ou **/Users**, pois criando na pasta do usuário, pode ser
perdido se o usuário for excluído. Com isso, veja o exemplo abaixo:Linux:
```shell
sudo mkdir -p /home/.dotfiles; cd $_
sudo chown -R $(whoami) /home/.dotfiles
sudo chmod -R 700 /home/.dotfiles
dotctrl init
```macOS:
```shell
sudo mkdir -p /Users/.dotfiles; cd $_
sudo chown -R $(id -un) /Users/.dotfiles
sudo chmod -R 700 /Users/.dotfiles
dotctrl init
```### --auto
Você pode contornar todos esses comandos acima usando a flag `--auto`. O **Dotctrl** criará automaticamente uma base
diretório para armazenar os dados, no entanto, você **DEVE** ter permissão sudo.> Recomendamos usar fortemente está opção caso tenha permissão.
```shell
dotctrl init --auto
```### --git
Esta flag faz com que o **Dotctrl** crie um repositório [git](https://git-scm.com) dentro do repositório **Dotctrl**.
```shell
dotctrl init --git
```Você também pode combinar está flag com a flag [`--auto`](#--auto):
```shell
dotctrl init --auto --git
```## pull
Com a base já criada, é hora de você PUXAR os elementos para a base do **Dotctrl** com o comando `pull`.
Puxe **UM** [elemento]() para o repositório **Dotctrl**:
```shell
dotctrl pull --e .zprofile
```Se você quiser fazer um **pull** massivo, faça:
```shell
dotctrl pull
```> 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).
## link
Depois de puxar o(s) elemento(s), crie links simbólicos para eles em seus locais originais:
```shell
dotctrl link --e .zprofile
```Se você quiser realizar um **link** massivo, faça:
```shell
dotctrl link
```> 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).
## unlink
Desvincule o elemento do repositório com o local de origem:
```shell
dotctrl unlink --e .zprofile
```Se você quiser **desvincular** elementos de forma massiva, faça:
```shell
dotctrl unlink
```> 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).
## restore
Este comando irá tirar um elemento do repositório **Dotctrl** e restaurar para seu local original:
```shell
dotctrl restore --e .zprofile
```Se você quiser realizar uma **restauração** massiva, faça:
```shell
dotctrl restore
```> Nota: Por padrão, ao restaurar elemento(s) para o local de origem, o **Dotctrl** NÃO remove os elemento do registro
> (`dotctrl.json`). Para limpar, veja [--autoclean](#autoclean).## repo
Este comando trás informações do repositório, veja abaixo alguns de seu subcomandos:
### --check
Faça uma verificação para ver se há elementos a serem vinculados:
```shell
dotctrl repo --check
```### --ls
Verifique os elementos já importados no repositório do **Dotctrl**.
```shell
dotctrl repo --ls
```### --info
Com o comando abaixo você pode ver algumas informações do repositório **Dotctrl**, como quantidade de pastas e arquivos,
o caminho absoluto do repositório e se a variável de ambiente `DOTCTRL_PATH` estiver ativa.```shell
dotctrl repo --info
```## find
Pesquisa qualquer elemento dentro do repositório do **Dotctrl**. Para isso, use o comando:
```shell
dotctrl find --name .zprofile
```> Nota: Envolva o elemento a ser encontrar com aspas duplas caso o mesmo tenha espaços no nome.
## config
Este comando irá manipular o arquivo de configuração do **Dotctrl**, veja abaixo alguns subcomandos do mesmo.
### --autoclean
Faz uma limpeza nos elementos presentes no arquivo de configuração do **Dotctrl**.
Qualquer 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.Geralmente o `--autoclean` é usado após usar o comando de [restauração](#restore) de elementos.
```shell
dotctrl config --autoclean
```### --view
Dê uma espiada no arquivo de configuração do **Dotctrl** pelo terminal.
### --open
Permite editar o arquivo de configuração do **Dotctrl** no próprio terminal usando o comando:
```shel
dotctrl config --open
```> Nota: Usa por padrão o editor `vim`, caso não tenha, irá tentar usar o `nano`, `emacs` ou `micro`.
### --lang
Use 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.
```shel
dotctrl config --lang
```## Flags globais
### --e (--element)
A flag **--e** ou **--element**, é responsável por manipular um elemento especifico do repositório **Dotctrl**.
Esta flag deve receber um elemento sem o caminho absoluto, apenas o relativo a partir da `$HOME`.
Exemplos:
* `dotctrl pull --e .zprofile`
* `dotctrl link --e .zprofile`
* `dotctrl unlink --e .zprofile`
* `dotctrl restore --e .zprofile`Se o elemento tiver espaços no nome, envolva-o entre aspas duplas. Exemplo: `dotctrl pull --e "arquivo legal.txt"`
### --f (--force)
A 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`.
## Arquivo de configuração (dotctrl.json)
Este é um exemplo de uma estrutura completa do arquivo de configuração (`dotctrl.json`) do **Dotctrl**:
```json
{
"dotctrl": {
"config": {
"editor": "vim",
"language": "pt_BR"
},
"elements": [
".zshrc",
".config/xfce4/terminal/terminalrc",
".config/Code/User",
"Images/Wedding"
],
}
}
```## Variável de ambiente
Por 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.
Se 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`.
Você 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`:
Linux:
```shell
export DOTCTRL_PATH="/home/.dotfiles"
```
oumacOS:
```shell
export DOTCTRL_PATH="/Users/.dotfiles"
```> NOTA: Lembre-se, ao criar esta variável de ambiente, você não poderá criar outros repositórios para **Dotctrl**.
## Atualizando
Se **Dotctrl** tiver novos recursos, atualize a linha de comando abaixo:
```shell
python3 -m pip install dotctrl -U --user
```## Mais comandos
Para obter mais informações de comando, use:
```
dotctrl [--help | -h]
```## Extras
### Deploy e Clone do repositório Dotctrl
Agora que você tem o controle de seus elementos, é hora de fazer o deploy dos mesmo em um serviço de git.
Este exemplo abaixo mostrará como realizar o deploy e clone no [GitHub](https://github.com).1 - Deploy:
A - Entrando na pasta raiz criada do **Dotctrl**:
Linux:
```shell
cd /home/.dotfiles
```macOS:
```shell
cd /Users/.dotfiles
```B - Criando repositório git, commit e salvando (push)
```shell
git remote add origin [email protected]:/dotfiles.git
git init
git add .
git commit -m "Update"
git push origin main
```2 - Clone:
Você 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:
Linux:
```shell
sudo mkdir -p /home/.dotfiles
sudo chmod -R 770 /home/.dotfiles
cd /home/.dotfiles
git clone [email protected]:/dotfiles.git .
dotctrl link --f
```macOS:
```shell
sudo mkdir -p /Users/.dotfiles
sudo chmod -R 770 /Users/.dotfiles
cd /Users/.dotfiles
git clone [email protected]:/dotfiles.git .
dotctrl link --f
```## Doação
Clique na imagem abaixo para ser redirecionado aos formulários de doação:
É muito importante você fazer uma doação para motivar a continuação de desenvolvimento do **Dotctrl**. :)
## Licença
O projeto está disponível como código aberto sob os termos da [Licença MIT](https://github.com/snakypy/dotctrl/blob/main/LICENSE) ©
## Creditos
Veja, [AUTHORS](https://github.com/snakypy/dotctrl/blob/main/AUTHORS.rst).