sdf_appunti/dotbot.org

* Dotbot

  Si tratta di uno strumento simile a GNU Stow ma che rispetto a questo
  presenta delle migliorie.

  Come Stow anche Dotbot funziona soltanto su Linux/MacOS. E' scritto
  in Python che, almeno sulle macchine Linux, è solitamente preinstallato.

  La metodologia standard per l'uso di Dotbot consiste nel creare un
  repository per contenere i dotfiles e, all'interno di questo, clonare
  come submodule Dotbot stesso. Questo sistema rende tutta la gestione
  in qualche modo "self contained" mentre Stow, ad esempio, deve essere
  installato.

  La pagine di riferimento per il progetto su Github è:
  [[https://github.com/anishathalye/dotbot][https://github.com/anishathalye/dotbot]] dove si trova anche la documentazione
  
* Partendo da zero

  Se si inizia a lavorare con Dotbot partendo da zero occorre creare un
  nuovo repository che andrà a contenere i files da gestire, assumiamo
  che il repository si troverà nella directory ~$HOME/.dotfiles~ e che
  questa sia già stata creata:

  #+begin_example
  # Mi posiziono nella directory del repository
  cd ~/.dotfiles
  # Inizializzo il repository se non esiste
  git init
  # Aggiungo dotbot come submodule
  git submodule add https://github.com/anishathalye/dotbot
  # Dico a git di ignorare eventuali modifiche alla workdir del submodule
  git config -f .gitmodules submodule.dotbot.ignore dirty
  # Copio il comando di "install" dal submodule nella root del repository
  cp dotbot/tools/git-submodule/install .
  # Creo il file di configurazione (vuoto)
  touch install.conf.yaml
  #+end_example
  
  A questo punto non si deve fare altro che iniziare a impostare il
  contenuto di ~install.conf.yaml~ e spostare i dotfiles dalla posizione
  origine all'interno del repository.

  Una volta impostato il tutto il comando ~install~ provvederà alla
  creazione dei link.

* Il file ~install.conf.yaml~

  E' il motore di tutto il procedimento. E' un file in formato [[https://it.wikipedia.org/wiki/YAML][YAML]] e come tale necessita
  di una corretta gestione dell'indentazione delle righe.
  Dotbot consente anche l'uso del formato [[https://www.json2yaml.com/][JSON]], in questo caso il file si dovrà
  chiare ~install.conf.json~ ~install.conf.yaml~ è suddiviso in "comandi":
  - Defaults :: Qui vanno le impostazioni di default valide per tutte la varie
    situazioni. E' utile per non dover specificare le stesse impostazioni
    in ogni singolo altro ramo.
  - Link :: Contiene, in forma di dizionario, gli abbinamenti tra destinazione
    e origine. L'origine è il file presente nel repository e deve essere
    specificato sempre relativamente alla radice del repository stesso (che
    è dove si sta eseguendo l'installer).
    Se si creano link a directory si deve omettere la barra finale.
  - Create :: Indica le directory che devono essere create. Utile per creare
    la struttura che poi andrà a contenere i link o che comunque è richiesta
    dalle varie applicazioni.
  - Shell :: Specifica i comandi di shell da eseguire. I comandi eseguiti
    fanno riferimento alla directory in cui l'installer viene eseguito.
  - Clean :: Specifica le directory che dovranno essere esaminate per la
    presenza di "dead links". Nel caso in cui si trovi la presenza di un
    link simbolico che non porta a niente questo viene eliminato.

  Ciascun "comando" prevede vari parametri, vedere la documentazione di Dotbot
  per approfondire.
  
* Impostiamo la gestione

  Con un editor andiamo a descrivere le opzioni di installazione in ~install.conf.yaml~
  
** Le impostazioni di default

   Le impostazioni di default sono quelle che, una volta specificate, valgono per
   tutti gli altri "comandi". Nello specifico vogliamo che ciascun link utilizzi
   l'opzione "relink" che rimuove il vecchio target se è un link simbolico.

   #+begin_example
     - defaults:
         link:
             relink: true
   #+end_example

** Facciamo rimuovere i "dead link"

   Con l'opzione ~clean~ si indicano le directory in cui deve avvenire un
   controllo per la verifica dei dead link verso il repository.

   #+begin_example
     - clean: ['~']
   #+end_example

** Impostiamo la creazione dei link simbolici

   #+begin_example
     - link:
         ~/.emacs.d: emacs/.emacs.d
         ~/.vim: vim/.vim
         ~/.vimrc: vim/.vimrc
   #+end_example

   Nell'esempio ho creato i collegamenti per VIM e Emacs. Ho preferito mantenere
   nel repository i nomi dei files e delle directory che iniziano con il
   punto, ma non è strettamente necessario.

   L'impostazione che ho dato è quella di avere nel repository delle directory
   che andranno a contenere tutti gli elementi di una applicazione.

   In questo semplice esempio si sono creati i soli link simbolici non sfruttando
   le possibilità di creare directory, eseguire script o utilizzare plugins.

** Il risultato finale

   Il risultato finale del contenuto di ~install.conf.yaml~ dovrebbe quindi essere:

   #+begin_example
     - defaults:
         link:
             relink: true

     - clean: ['~']

     - link:
         ~/.emacs.d: emacs/.emacs.d
         ~/.vim: vim/.vim
         ~/.vimrc: vim/.vimrc
   #+end_example
   
** Copiamo nel repository

   A questo punto dobbiamo spostare nel repository i files e le directory.

   Occorre spostare la directory ~$HOME/.emacs.d~ in ~$HOME/.dotfiles/emacs/~

   Occorre anche spostare sia il file ~$HOME/.vimrc~ che la directory ~$HOME/vim~ in ~$HOME/.dotfiles/vim/~

** Commit & push

   Stiamo lavorando in un repository. Non dimentichiamo di fare commit e push!

** Install

   Una volta configurato il tutto non resta che far lavorare dotbot.

   Con il comando ~install~ (presente in ~$HOME/.dotfiles~) saranno creati i
   link simbolici e fatto tutto quanto indicato nel file di configurazione.
   
* Bootstrap

  Una volta creato il repository, configurato e messo su di un server raggiungibile
  il bootstrap in un ambiente nuovo si riduce ad una linea di codice:
  #+begin_example
    cd ~ && git clone https://url/to/git/server/.dotfiles && cd ~/.dotfiles && ./install
  #+end_example

  L'esempio assume l'uso di un repository che si chiama ~.dotfiles~ che sarà clonato
  nella ~$HOME~ mantenendo lo stesso nome. *CAVEAT*

  Dotbot NON crea i link simbolici se il target già esiste come file o directory normale.
  Eventuali link simbolici esistenti sono sostituiti in presenza della direttiva ~relink: true~
  
* Informazioni aggiuntive
  
** Plugins

   Una caratteristica interessante di dotbot è quella di avere un'architettura
   che consente l'uso di plugins.

   Tra i plugins disponibili ([[https://github.com/anishathalye/dotbot/wiki/Plugins][https://github.com/anishathalye/dotbot/wiki/Plugins]])
   si trovano, ad esempio, quelli per clonare repository git, per installare
   Visual studo code, per installare Rust.

   La lista non è enorme, ma comprende comunque elementi utili.
  
** Repository di esempio

   Oltre all'autore del software che nel suo spazio su Github rende disponibile
   la propria gestione dotfiles, nelle pagine Wiki del progetto si trova una
   (lunga) [[https://github.com/anishathalye/dotbot/wiki/Users][lista di utenti che gestiscono i propri dotfiles con dotbot]]

** Tips-And-Tricks

   Nella pagina wiki [[https://github.com/anishathalye/dotbot/wiki/Tips-and-Tricks][tips & triks]] del progetto si trovano spunti interessanti
   sia per risolvere situazioni particolari, ma anche come punti di partenza
   per approfondire ulteriori argomenti correlati alla gestione dei dotfiles.