Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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".

[![Tests](https://github.com/snakypy/dotctrl/workflows/Tests/badge.svg)](https://github.com/snakypy/dotctrl/actions)
[![Python Versions](https://img.shields.io/pypi/pyversions/dotctrl)](https://pyup.io/repos/github/snakypy/dotctrl/)
[![Updates](https://pyup.io/repos/github/snakypy/dotctrl/shield.svg)](https://pyup.io/repos/github/snakypy/dotctrl/)
[![Python Whell](https://img.shields.io/pypi/wheel/dotctrl)](https://pypi.org/project/wheel/)
[![PyPI](https://img.shields.io/pypi/v/dotctrl)](https://pypi.org/project/dotctrl/#history)
[![PyPI - Implementation](https://img.shields.io/pypi/implementation/dotctrl)](https://pypi.org/project/dotctrl)
[![Isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![Mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![Code style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/dotctrl)](https://pypi.org/project/dotctrl/#files)
[![GitHub license](https://img.shields.io/github/license/snakypy/dotctrl)](https://github.com/snakypy/dotctrl/blob/main/LICENSE)

----------------

_{Construído com ❤︎ por:

William Canin no tempo livre,

ao som da playlist: Bursting Of The Tympanum}

Sumário

Sobre

Características

Requisitos

Instalando

Usando
- init
- pull
- link
- unlink
- restore
- repo
- find
- config

Flags Globais

Arquivo de configuração (dotctrl.json)

Variável de ambiente

Atualizando

Mais Comandos

Extras
- Deploy e Clone do repositório Dotctrl

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:

![](https://raw.githubusercontent.com/snakypy/assets/main/dotctrl/gifs/demo.gif)

# 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"
```
ou

macOS:

```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).