Un tutorial per scrivere usando Git (e il Markdown)
Ecco come funziona il sistema che ho messo in piedi per poter sincronizzare quello che scrivo tra dispositivi diversi (Mac, iPad e iPhone) usando GitHub e il markdown
Da molto tempo sono alla ricerca della leggerezza nella scrittura. Poter lavorare senza essere vincolati dalla pesantezza di software come Word di Microsoft, formati barocchi come docx e problemi di sincronizzazione attraverso dispositivi diversi, è stato a lungo un sogno. Non è necessario viaggiare da un continente all'altro per poterlo desiderare: anche potersi muovere con semplicità tra dispositivi differenti e scrivere ad esempio sull’iPad Pro con la nuova Magic Keyboard senza problemi è una forma di libertà.
L’estate, che è da sempre il momento in cui si riprende fiato e si ha tempo per portare avanti qualche progetto personale, questa volta è stata fondamentale per analizzare e riprogettare tutto il flusso di lavoro pensato sia per la produttività individuale che per la collaborazione con altri.
Premessa: il problema da affrontare
Il problema da affrontare, almeno per quel che mi riguarda, è quello di avere un sistema che permetta di scrivere con leggerezza e velocità su una serie di dispositivi vari (Mac, iPhone, iPad) sia con connessione fissa che con connessione pubblica (WiFi) o via telefono (3G, 4G) senza cadere nella trappola di software e piattaforme proprietarie, che oggi ci sono e domani chissà.
Anni fa la scelta è stata quella di passare al markdown, il linguaggio di marcatura leggero creato da John Gruber, abbandonando Word (che dopo la versione 5.1 per Mac, diciamocelo, non è stato più lo stesso), Pages e tutti gli altri sistemi tradizionali. Nel caso del software di Microsoft, la scelta è stata fatta anche per togliersi di torno sia i costanti problemi di sicurezza del software stesso che del formato dei documenti, utilizzato più volte per veicolare attacchi nefasti con le macro e come “contenitore” di trojan. Si può vivere senza MS Word? Certo, e benone.
Parte prima
Cosa rimane e quali sono i problemi
Nel flusso di lavoro del sottoscritto a questo punto come software “legacy” rimane solo Scrivener, per la capacità di coordinare progetti estremamente complessi (come libri) in modo ricco, completo e flessibile, ma non è più utilizzato da tempo come contenitore del lavoro quotidiano del cronista della tecnologia.
I problemi affrontati nel tempo sono stati: trovare degli editor di testo capaci di funzionare bene, in maniera continua ed affidabile; trovare una modalità di archiviazione dei documenti di testo semplice (leggeri per definizione) che permetta una sincronizzazione semplice ed efficace, riducendo al minimo le copie in conflitto; spendere il meno possibile e se possibile non rimanere prigionieri di formati e piattaforme proprietari.
Difendersi dai formati occulti
Si potrebbe pensare che utilizzare il testo semplice con la formattazione in markdown possa essere un modo che è in grado di resistere alla prova del tempo e svincolare dal rischio dell’obsolescenza. Non è solo questo, però. Ogni volta che una app propone un sistema di organizzazione dei dati proprietario, il rischio si ripresenta.
Ad esempio, sistemi come quelli offerti da Bear e soprattutto da Ulysses, due popolari app per la scrittura in markdown in ambiente Apple, hanno questo problema: non offrono alternative e sfruttano un loro database per contenere i singoli documenti di testo, aggiungendo dei metadati che non sono più esportabili. Se anche si tira fuori il singolo file di testo, è la struttura complessiva che non è più facilmente ricreabile, o in alcuni casi impossibile da ricreare. Usare quel tipo di app è come mettere tutto in un altro computer che sta dentro al nostro computer, con un suo filesystem e una sua logica proprietari. Se per caso l’app non funziona o non viene più aggiornata, si rischia di non poter più accedere al proprio lavoro. Si può (quasi sempre) esportare, certamente, ma è una operazione laboriosa che diventa problematica se il tempo è poco o i documenti sono centinaia.
In principio c'era il filesystem e Dropbox
Ecco perché ho scelto inizialmente come modello di archiviazione dei documenti il file system del MacBook, utilizzando poi per la sincronizzazione Dropbox. Questa soluzione è stata la mia preferita per molto tempo perché si è dimostrata a lungo la più affidabile (Dropbox fin dall’inizio ha fatto molto bene il suo lavoro) e la più trasparente (si usano semplicemente le cartelle del sistema operativo e si spostano i documenti avanti e indietro, come se fossero documenti “normali”) utilizzando una metafora perfettamente comprensibile: quello che sta dentro la cartella di Dropbox è presente e viene sincronizzato anche sugli altri dispositivi connessi allo stesso account.
Più nel dettaglio, ho sempre preferito Dropbox a Box (tecnicamente molto simile) per via della maggiore diffusione all’interno delle app iOS, e alla tecnologia di iCloud per la sua maggiore inaffidabilità (soprattutto in passato i tempi di sincronizzazione erano imprevedibili, spesso lunghissimi, e c’erano anche numerosi casi di copie in conflitto degli stessi documenti, soprattutto se con connessione via cellulare) oltre che per la metafora differente (dove trovo sul computer i file messi su iCloud Drive? E su iPhone e iPad?).
Il problema è però diventato anche un altro: Dropbox ha cominciato a “comportarsi male”, sia per il continuo cambiare delle sue API che mettono in fuorigioco parecchie app iOS di terze parti, sia perché l’azienda ha deciso di concentrarsi sempre più sui servizi e sta diventando sempre di più una piattaforma proprietaria. Il rischio finale, insomma, secondo me è quello di ritrovarsi di nuovo ingabbiati in una piattaforma chiusa o quantomeno di pagare per servizi non necessari. Quindi, è ricominciata la mia ricerca di una nuova soluzione per lavorare è stata quella di cercare un altro approccio, questa volta veramente “aperto”. L’obiettivo ultimo è poter lavorare indifferentemente dalla piattaforma sulla quale ci si trova: macOs, iPadOS, Windows, Linux, BSD, Android. In questo modo restare sui prodotti di Apple deve essere un piacere e una scelta, anziché un bisogno o un obbligo.
Git e GitHub
La risposta che ho trovato questa estate è Git, il software open source creato da Linus Torvalds per funzionare da sistema di controllo di versione distribuito. Git è nato per il versionamento del codice sorgente del software, che però è sostanzialmente fatto da file di testo e quindi va bene anche per la prosa e la poesia se scritta in testo semplice. È inoltre un software nato per essere collaborativo e coordinare tra loro i repository locali di tantissimi utilizzatori, quindi va benissimo per chi come il sottoscritto deve semplicemente gestire tre o quattro tra computer, tablet e telefoni. Inoltre, Git è uno dei progetti open source più grandi e mantenuti al mondo, quindi non c’è rischio di rimanere prigionieri di un sistema destinato all’oblio e alla decadenza. Anzi, a differenza di iCloud e Dropbox, è disponibile su un numero molto più ampio di piattaforme, in caso un giorno ci sia il bisogno di fare una migrazione improvvisa da macOS e iPadOS verso altri sistemi.
Inoltre, Git viene fornito come servizio cloud: questo vuol dire che è possibile sincronizzare il proprio repository locale con uno nel cloud. Ed è la rivoluzione, perché in questo modo si possono far puntare i vari dispositivi al repository nel cloud e si è risolto il problema della sincronizzazione. Chi offre questo servizio? In realtà un buon numero di aziende (GitHub, GitLab e altri) in maniera gratuita anche con repository privati. Il servizio è perfettamente standard (non ci sono caratteristiche e dialetti “devianti” per Git) e facile da usare.
Infine, Git in modalità server si può installare anche in locale. Può essere utilizzato infatti anche in modalità server autogestita e ai più smanettoni basta un Raspberry Pi attaccato al router di casa per essere totalmente autonomi e non aver bisogno di altro.
Parte seconda
La via del markdown
Con il linguaggio di marcatura leggero creato da John Gruber è possibile aggiungere pochi elementi strutturali al testo semplice (grassetti, corsivi, link, titoli e titoletti) che sono creabili e poi leggibili anche senza bisogno di un editor specializzato. Il vantaggio è poter avere la struttura del testo, che poi potremo arricchire con lo stile che vogliamo, esportandola ad esempio come html (pulito da tutte le formattazioni nascoste e spesso senza senso di Word, ad esempio) per inserirla in un blog, per trasformarla in pdf, rtf, docx, per archiviarla in un formato che, grazie a Unicode, resterà leggibile per moltissimo tempo.
Avendo stabilito questo come punto di partenza per la scrittura, ci siamo liberati non solo dei programmi con formati proprietari (MS Word) ma evitiamo anche i programmi che strutturano i dati all’interno di un loro database (Bear e Ulysses) ed evitiamo i sistemi di sincronizzazione proprietari che sono relativamente controllabili (GoogleDrive, OneDrive, iCloud Drive, Dropbox, Box e tutti gli altri). Non perché siano di per sé sbagliati, ma perché sono come dei silos che strutturano i dati (cioè i nostri documenti) in un certo modo e ci vincolano a quel fornitore di servizio e a quella piattaforma. Andiamo incontro alla libertà, invece.
La via di Git
Abbiamo detto che scegliamo Git. La struttura del lavoro è semplice: dobbiamo creare un repository che sia il contenitore dei nostri documenti di testo semplice con i nostri appunti, le nostre note, i nostri articoli, il nostro diario e tutto il resto che finisce con txt, organizzato liberamente in cartelle e sottocartelle secondo il criterio che per noi funziona meglio. Lo creeremo su Mac, lo sincronizzeremo con GitHub, il servizio gratuito diventato da alcuni mesi di proprietà di Microsoft, in un repository online gratuito, e da qui a cascata potremo sincronizzare gli altri nostri computer “clonando” il repository remoto e poi aggiornandoli man mano tutti quanti.
Per occuparci di Git su Mac occorre installarlo. La soluzione “semplice” è usare GitHub Desktop, client a interfaccia grafica gratuito realizzato da quelli di GitHub e che funziona molto bene. Scegliamo invece la via del purista, e per farlo utilizziamo la riga di comando e Homebrew (il gestore di pacchetti che mancava al Mac), ma ricordiamo ancora una volta che è possibile procedere anche con un altro modo, cioè utilizzando client grafici di terze parti che si appoggiano sopra l’installazione fatta sul Terminale oppure procedono direttamente loro all’installazione di Git. Non vogliamo sposare quest’ultimo approccio perché ci renderebbe di nuovo dipendenti da un singolo software. Invece, installiamo Git dalla riga di comando tramite Homebrew. È sufficiente il comando:
brew install git
E il gioco è fatto. Una volta installato Git dobbiamo puntare la directory di lavoro del Terminale sulla cartella dove abbiamo deciso che risiederà il nostro archivio di materiali (da ora in poi o chiamiamo “repository”) nel filesystem del Mac. Lo avremo già popolato dei nostri file di testo pre-esistenti e magari avremo organizzato la gerarchia delle cartelle a seconda di quello che ci serve. Non è fondamentale aver già fatto tutto, si può anche partire con un repository completamente vuoto (basta che ci sia la cartella-contenitore in cui viene creato), ma chi scrive aveva già un bel pregresso di materiale organizzato ed è partito con quello.
Come far funzionare Git
Qui brevemente i comandi che dobbiamo dare per creare effettivamente il repository, molti dei quali non serviranno più, e poi procediamo a spiegare come funziona a regime tutto quanto il meccanismo.
Prima però bisogna fare un po' di housekeeping. Ogni prima installazione di Git richiede di passare alcuni parametri che, se digitati con l'argomento --global si applicano a tutti gli utenti. In particolare, facendo attenzione che nella prima riga servono le virgolette e nella seconda no):
git config --global user.name "IL VOSTRO NOME"
git config --global user.email LAVOSTRA@EMAIL
Altre due configurazioni che sono prudenti (le applico sempre)
git config --global core.filemode false
git config --global core.autocrlf false
E poi una configurazione obbligatoria per quando, anziché "spingere" il contenuto del vostro repo locale verso quello su GitHub (push) lo vorrete "tirare" dal remoto in locale (pull). Potete scegliere se fare git fetch seguito da git merge oppure (come vi consiglio) configurare git in maniera tale che pull non faccia rebase dell'intero repo ma solo merge
git config --global pull.rebase false
Con questa configurazione, quando vorrete sincronizzare il repository locale con le modifiche fatte su quello remoto, vi basterà un solo comando
git pull
Se poi aveste bisogno di cambiare temporaneamente questo comportamento, potete farlo volta per volta usando gli argomenti --rebase, --no-rebase oppure --ff-only (--ff vuol dire fast forward)
Ecco il nostro repository
Adesso chge siamo pronti, cominciamo a creare il repository. Io ho messo tutti i dati (cartelle e file di testo) dentro una cartella chiamata immodestamente “memex”, e poi ho portato il focus del Terminale su ~/memex (la cartella è nella root della home del mio utente ma potete metterla dove volete, ad esempio nella cartella "Documenti" e sarebbe in effetti una cosa più ordinata) e digitato il comando (seguito da invio):
git init
Dopodiché bisogna aggiungere i file presenti nella directory (questa operazione si ripeterà ogni volta che bisogna aggiornare) e fare commit. Dopo ogni riga premere invio. Nella prima riga attenzione al punto, preceduto da uno spazio.
git add .
git commit -m “Il mio primo commit!”
A questo punto, prima di fare git push, è necessario spostarsi su GitHub e creare il nuovo repository dove si andrà a sincronizzare
Configurare GitHub
Dopo aver creato un nostro account gratuito su GitHub, creiamo un repository (il nome non deve necessariamente essere lo stesso di quello che sincronizzeremo) e lasciamolo vuoto, anche senza file readme.
Per fare la sincronizzazione ci sono due modi, uno meno e uno più sicuro. Potremmo usare username e password creata con il nostro account utilizzando una connessione di tipo https, oppure possiamo generare sul Mac una chiave crittografica per fare la connessione SSH. Seguiamo la seconda strada, anche perché la prima è stata deprecata e presto non funzionerà più.
Sul Mac occorre generare una coppia di chiavi, pubblica e privata, usando l’algoritmo Rsa. Il comando è semplice:
ssh-keygen -t rsa -b 4096 -C "LAVOSTRAEMAIL@TRAVIRGOLETTE"
Il comando ssh-keygen crea la chiave basata sul nostro indirizzo di email e ha tre argomenti. Il primo, -t, permette di selezionare il tipo di algoritmo (in questo caso, rsa); il secondo, -b, permette di selezionare la dimensione della chiave (4096 è un’ottima scelta); infine, -C (attenzione alla maiuscola) permette di aggiungere un commento alla fine del file della chiave che non modifica la chiave stessa ma serve per associarla a github, ad esempio).
La risposta del terminale sarà:
Generating public/private rsa key pair.
Enter file in which to save the key ($HOME/.ssh/id_rsa):
Premendo invio viene salvata nella directory di default ($HOME è il modo per indicare la directory home dell’utente attivo, anche non conoscendone il nome). Consiglio vivamente di scegliere questa opzione.
A questo punto il programma ci chiede anche una password per proteggere la chiave: sceglietene una buona, mi raccomando.
Enter passphrase (empty for no passphrase):
All’interno della directory invisibile .ssh che sta nella vostra home (~) ci sono i due file con la chiave rispettivamente privata e pubblica, id_rsa e id_rsa.pub. Per aggiungerla su GitHub e farci riconoscere, basta andare nel menù in alto a destra del sito (una volta loggati) selezionare la voce “Impostazioni”. Al suo interno selezionare “SSH and GPG keys” e da qui selezionare nuova chiave SSH.
C’è a questo punto una schermata con un campo “Title” e un campo “Key” da compilare: il titolo serve per ricordare di quale chiave stiamo parlando. Invece nel campo “key” bisogna incollare il contenuto della chiave. Torniamo un attimo al terminale e digitiamo il comando:
cat ~/.ssh/id_rsa.pub
L’output è una serie di caratteri che si possono copiare con il mouse e incollare nel browser.
Funziona. A questo punto, per evitare di mettere la password ogni volta che usiamo la chiave SSH, dobbiamo aggiungerla all’SSH Agent. Basta un comando:
ssh-add ~/.ssh/id_rsa
Adesso siamo pronti per sincronizzare il nostro repository locale con GitHub!
Sincronizziamo il master locale con quello remoto
Per procedere alla sincronizzazione dobbiamo semplicemente fare come segue.
Assicuriamoci innnanzitutto che il terminale punti alla directory dove c’è il repository. Abbiamo già aggiunto tutti i file del repository (git add .) e fatto “commit”. Prima di poter fare push (o pull per sincronizzare il contenuto remoto) dobbiamo creare il collegamento. Copiamo dalla pagina web di GitHub l’indirizzo SSH del nostro repository remoto che ora è vuoto.
A questo punto copiamolo al posto dell’indirizzo in questo comando:
git remote add origin
Il comando di git “remote add origin” indica che deve essere aggiunta una origine del progetto anche a un repository remoto. In pratica, siccome tutte le copie dei repository sono uguali e di pari dignità (non c’è un “centro” assoluto), gli stiamo dicendo di aggiungere il repository locale a quello remoto vuoto.
Prepariamo il remoto:
git remote -v
Infine, spostiamo il materiale del repository locale su quello remoto:
git push origin master
Fatto. Adesso abbiamo due repository identici. Se facciamo cambiamenti in uno dei due, basta seguire la sequenza di comandi viste prima (add-commit-push) per aggiungere il lavoro fatto dall’area di staging locale a quella del repository locale e poi spostarle su quello remoto. Se invece si fanno cambiamenti in quello remoto e si “committano” e “pushano”, bisogna scaricarli in locale, quindi fare pull e merge (ma solitamente pull fa anche questa seconda azione, ricordate la configurazione globale poco sopra?). Oppure risolvere i potenziali conflitti.
Parte terza
Il client per sincronizzare Git su iOS/iPadOS
La bellezza di git sta da un lato nella potenza e flessibilità, e dall’altra nel fatto che è open source e talmente tanto diffuso (è stato creato da Linus Torvalds, il papà di Linux, e viene usato da decine di milioni di sviluppatori in tutto il mondo) da non rischiare di trasformarsi in un vicolo cieco tecnologico né in una trappola proprietaria che costringa a pagare abbonamenti o che renda i propri dati “prigionieri” di un servizio chiuso, neanche in versione online (ci sono GitHub, Bitbucket e GitLab, e molti altri servizi di questo tipo).
Utilizzarlo su Mac richiede l’uso o della versione a riga di comando del software originale (che a sua volta richiede installare Homebrew, tramite quello scaricare e installare git, e poi creare una chiave pubblica e privata per la connessione SSH tra il proprio Mac e GitHub, come abbiamo visto nelle due parti precedenti di questo articolo) oppure uno dei tanti client con interfaccia grafica disponibili, gratuiti o a pagamento. Ottimo GitHub Desktop della stessa azienda e completamente gratuito, ma ci sono ad esempio anche estensioni Chrome o mille altri sistemi.
Working Copy & iA Writer
Su iOS/iPadOS in teoria è possibile utilizzare la riga di comando con delle app ottime come ad esempio ShellFish per le connessioni SSH, anche se è davvero ottimo Blink, molto buoni anche a-Shell (dell'autore di Working Copy), Cathode (divertente) e LibTerm (validissimo). Infine, il mio amore impossibile (perché limitato come editor) è iVim, e quello ben più flessibile che è Buffer Editor. Sennò si usa CoGoEdit o (meglio) Textastic.
Invece, mi sono innamorato di uno schema diverso, basato su un sistema di app binario centrato su Working Copy, un software specializzato come client git a interfaccia grafica che offre una ottima performance. Ci sono anche altri, come GitDrive e Git2Go, ma Working Copy funziona molto bene, soprattutto perché è un buon cittadino di iOS e consente alle altre app di accedere alle cartelle con i suoi documenti.
Working Copy presenta infatti i dati contenuti nella sua sandbox all’app File e a tutto iOS/iPadOS. Se un’altra app è compatibile è possibile farla “puntare” ai dati contenuti dentro Working Copy e lavorare direttamente su quelli, senza bisogno di esportarli. È esattamente quanto succede con iA Writer, da anni il mio editor di testo preferito e soprattutto una app che costa sì cara, ma si paga una volta sola (niente abbonamenti o acquisti in app) e dura tantissimo (l'attuale versione c'è da più di cinque anni e viene sistematicamente aggiornata). Inoltre, a parte lo stile minimalista delizioso, è anche multipiattaforma e si può comprare per Mac, iOS/iPadOS, Windows e Android.
Il gioco di prestigio per iPad
Tutto questo per arrivare al vero gioco di prestigio da fare su iPad Pro. La strada su Mac è abbastanza semplice: si crea una cartella (mi raccomando: sempre fuori da cartelle contenute in Dropbox, iCloud Drive o altri sistemi di sincronizzazione di terze parti, per evitare danni all’integrità del repository) si editano i documenti di testo con iA Writer o l’editor di markdown che preferite, e poi si “committa” e “pusha” con git (client desktop o cli); salvo fare quando serve il percorso inverso: si fa pull e poi si editano i dati aggiornati e sincronizzati con il repository nel cloud, in questo caso su GitHub.
Entrare in questo circuito anche con iPad Pro e la nuova tastiera Magic Keyboard è una tentazione troppo forte per resisterle. Ecco allora mio schema di lavoro: il repository dei dati sta dentro Working Copy e iA Writer “aggiunge” le cartelle (con una operazione che gli autori hanno chiamato “Add Location”, lasciando l’espressione in inglese anche se l’interfaccia di iA Writer è tutta in italiano) e permette di salvare un riferimento a queste cartelle direttamente nelle posizioni della Libreria di iA Writer. Questo consente di creare nuovi documenti ed editare quelli esistenti (ma anche di creare nuove cartelle, o cancellare documenti e cartelle) dentro iA Writer. Dopodiché, quando si è finito, si passa a Working Copy, che segnala i cambiamenti già avvenuti, e a quel punto basta premere il pulsante con l’icona dell’impronta digitale per poter fare commit+push in un colpo solo. Invece, per fare pull e merge basta “tirare giù” la lista dei repository o il singolo repository nella finestra come si fa ad esempio per aggiornare il feed di Twitter o della posta dentro Mail.
In conclusione
Il meccanismo a cui sono arrivato, come ho ripetuto varie volte sopra, è un flusso di lavoro che funziona se chi lo vuole usare ha determinati bisogni. Il primo è quello di voler utilizzare il markdown, avere familiarità con le tecnologie un po’ più evolute (riga di comando, homebrew e altro), magari voler collaborare a progetti più ampi.
Le applicazioni sono varie: con questo sistema si può ad esempio lavorare in un numero anche molto elevato di persone alla realizzazione dei testi per siti web collaborativi, documenti strutturati (ricerche scolastiche o universitarie, piuttosto che la documentazione aziendale di progetti complessi) oppure si può creare un proprio repository magari per creare il proprio sito web statico (Working Copy gestisce anche le anteprime html locali), oppure come meccanismo di backup sicuro e di sincronizzazione tra computer diversi.
Quest’ultimo è il mio caso che, oltretutto, per lavoro devo provare in continuazione computer, telefoni e tablet di marche e con sistemi operativi diversi, continuando ad essere produttivo anche su macchine che non supportano i medesimi standard tecnologici. Per questo git si è rivelato, questa estate, il pivot per un progetto di trasformazione digitale personale molto buona e molto interessante, almeno ad avviso di chi scrive, che ho cercato di documentare in questo articolo. Il quale, come tutto questo sito, è interamente costruito utilizzando queste tecnologie (Git e il markdown).
PS: Visual Studio Code
La cosa bella della libertà del markdown è la possibilità di cambiare editor quando è più comodo. In questo momento, ad esempio, sto aggiornando la pagina di questo articolo su un Mac mini M1 collegato a un monitor curvo UltraWide da 35 pollici di LG che sto testando per delle recensioni. Non solo utilizzo la soluzione Git+markdown, ma sto utilizzando anche la versione nativa appena uscita (siamo ai primi di marzo del 2021, come vola il tempo) di Visual Studio Code (opens new window), l'editor di codice della Microsoft che ha conquistato un posto nel cuore di milioni di sviluppatori in tutto il mondo perché è leggero, semplice e orientato alla scrittura, nonostante sia una app Electron. E la nuova versione per M1 fila che sembra una scheggia. Se preferite però la versione compilata dalla community (l'equivalente di Chromium rispetto a Chrome), che siete sicuri che non "telefona a casa", potete scaricare invece VSCodium (opens new window) oppure se usate Homebrew installarlo direttamente brew install --cask vscodium.