Création d’un dépôt
Créer un dépôt local
Pour tout nouveau projet que l’on souhaite versionner, il est nécessaire de créer un nouveau dépôt. C’est ensuite dans ce dépôt que Git stockera toutes nos informations. Pour cela, il faut se placer dans le dossier racine du projet. Par exemple, si le projet est un site web simple, nous pouvons imaginer que le dossier qui contiendra le projet soit nommé www. Dans notre cas, le dossier qui va contenir le code du projet se nomme depot. Il faut donc se placer dans ce dossier et exécuter la commande suivante :
git init
Git confirme la création du dépôt avec le message suivant :
Initialized empty Git repository in /Users/dauzon/Projets/depot/.git/
Cette action va créer un dossier nommé .git à la racine du projet. Sur la plupart des explorateurs de fichiers, ce dossier est par défaut invisible. Vous pouvez utiliser la ligne de commande pour visualiser ce dossier avec la commande ls -la pour les systèmes Linux ou macOS, mais également pour Windows en utilisant l’outil Cygwin.
Par défaut, la création d’un dépôt crée automatiquement une branche master. Pour changer le nom de cette branche, il est possible de définir l’option de configuration init.defaultBranch comme dans l’exemple ci-dessous.
git config --global init.defaultBranch main
touch README.md
git init
Dépôt Git vide initialisé dans /Users/dauzon/git3eme/.git/
git add README.md
git commit -m "README : add file"
[main (commit racine) e18c7a7] README : add file
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 README.md
git branch
* main
Le contenu du dossier .git
Le dossier .git héberge tout le contenu du dépôt utilisé par Git. De manière pragmatique, nous allons visualiser les dossiers et fichiers présents dans ce dossier. Pour cela, il faut se placer dans le répertoire .git en utilisant la commande cd :
cd .git
ls -la
Le système d’exploitation nous affiche alors une liste de fichiers et de dossiers :
-rw-r--r-- 1 dauzon staff 23 8 jui 23:30 HEAD
drwxr-xr-x 2 dauzon staff 68 8 jui 23:30 branches
-rw-r--r-- 1 dauzon staff 137 8 jui 23:30 config
-rw-r--r-- 1 dauzon staff 73 8 jui 23:30 description
drwxr-xr-x 11 dauzon staff 374 8 jui 23:30 hooks
drwxr-xr-x 3 dauzon staff 102 8 jui 23:30 info
drwxr-xr-x 4 dauzon staff 136 8 jui 23:30 objects
drwxr-xr-x 4 dauzon staff 136 8 jui 23:30 refs
Chacun de ces fichiers ou dossiers contient des éléments que Git utilise pour suivre notre code. Voici une liste des fichiers et dossiers et leur contenu (certains termes peuvent paraître obscurs, mais ils seront traités dans la suite de ce livre) :
-
HEAD : contient la référence du commit à partir duquel on travaille. C’est une référence qui est dépendante de la branche sur laquelle nous sommes situés. Dans la suite de ce livre (et dans de nombreux cas), HEAD désignera...
Le fichier README
Une bonne pratique lors de la création d’un dépôt consiste à expliquer le projet dans un fichier README à la racine du projet. Ce fichier est celui que vous consultez sur la page GitHub principale d’un projet. Comme exemple, il est possible de regarder les pages GitHub des projets de Django et de Bootstrap en consultant les liens suivants :
Sur ces pages se trouve un bloc contenant les dossiers et les fichiers à la racine du projet. En dessous de ce bloc se trouve le bloc nommé README.md qui contient la présentation du projet. Le fichier README de Bootstrap contient l’extension md pour Markdown et celui de Django contient l’extension rst pour reStructuredText. Ce sont deux formats abordés dans la suite de ce chapitre.
La présentation d’un projet est très importante et ne doit pas être négligée. Cette présentation est surtout à destination des développeurs qui utiliseront ou participeront au projet. Elle doit être très claire et contenir plusieurs parties :
-
Une partie présentant le projet : ses fonctionnalités, ses dépendances, etc. Cette partie doit être la plus compréhensible possible. Même un utilisateur débutant doit comprendre cette partie sans difficulté.
-
Une partie expliquant très rapidement l’utilisation du projet. Si c’est une bibliothèque, il faut présenter en 5 à 10 lignes de code la manière de l’utiliser. Cette partie ne sert pas de documentation, mais permettra aux futurs utilisateurs d’appréhender la facilité d’utilisation du projet.
-
Des liens ressources : vers une documentation plus complète, vers le site officiel, etc.
-
Les informations...
Markdown
1. Présentation
Markdown est un langage de présentation qui gagne en popularité depuis plusieurs années, comme le montre le graphique Google Trends ci-dessous :
Source : https://trends.google.fr/trends/explore?date=all&q=markdown
Ce langage n’est pas un langage de présentation avec une structure XML comme l’est HTML. Ce langage a été conçu dans le but d’être lisible directement en mode texte, ce qui l’a rendu très populaire chez les développeurs. En effet, un format comme le Markdown peut être consulté en mode texte et donc peut facilement être versionné. Il est d’ailleurs possible d’exporter des fichiers Markdown facilement vers du code HTML ou d’autres formats.
La syntaxe officielle est documentée sur le lien suivant : http://daringfireball.net/projects/markdown/syntax
Certaines syntaxes ne sont pas officielles, mais sont généralement bien supportées par les logiciels et bibliothèques s’interfaçant avec Markdown. Elles permettent d’ajouter des fonctionnalités absentes du format officiel. Les fichiers Markdown portent généralement l’extension .md.
Voici un exemple de fichier Markdown très simple d’un jeu fictif et son affichage sur GitHub :
# Stratégiii : le meilleur de la stratégie
## Fonctionnalités
+ 64 unités différentes !
+ La **meilleure IA** jamais vue !
Voici la manière dont ce fichier sera affiché sous GitHub :
2. Éléments de syntaxe
a. Titres
En Markdown, il est possible d’utiliser les titres sur six niveaux comme en HTML. Ces titres sont définis par un nombre précis de dièses au début du titre.
Par exemple un titre principal (équivalent...
reStructuredText
1. Présentation
reStructuredText est un autre format de présentation au même titre que Markdown. Il est un peu moins populaire que Markdown, mais propose certaines options qui sont absentes de Markdown.
La documentation officielle est très complète : http://docutils.sourceforge.net/rst.html#reference-documentation
La présentation de la syntaxe de reStructuredText sera plus succincte, car il convient à des usages plus poussés que Markdown et son apprentissage dépasse le cadre de ce livre. Il convient juste de garder à l’esprit que les possibilités de reStructuredText vont bien au-delà des quelques exemples ci-dessous.
Les fichiers reStructuredText portent généralement l’extension .rst.
2. Éléments de syntaxe
a. Titres
Pour les titres, il faut souligner ceux avec une suite de caractères. Ces caractères peuvent être nombreux. Voici la liste, conseillée par la documentation officielle, des caractères utilisables pour définir les titres : = - ` : . ’ " ~ ^ _ * + #
Voici un exemple composé de plusieurs titres :
Titre de niveau 1
===================
Titre de niveau 2
----------------------
Titre de niveau 1
===================
La hiérarchie des titres n’est pas définie par le format, c’est-à-dire que reStructuredText va directement choisir les niveaux qui conviennent. Pour le premier titre qu’il va rencontrer, il va définir le caractère de soulignage comme étant celui utilisé pour les titres de premier niveau. Et pour chaque titre souligné avec un autre caractère, il définira un niveau inférieur.
De cette manière, notre exemple aurait très bien pu être écrit ainsi sans changer l’importance...
Outils pour travailler avec Markdown
Du fait de sa grande popularité, Markdown s’est vu doté de nombreux outils au fil des années. Les développeurs, les blogueurs et même les auteurs de l’édition traditionnelle se sont intéressés au format, d’où la grande diversité d’outils.
1. Sublime Text
Ce n’est pas l’outil qui gère le mieux le Markdown, en revanche, c’est l’éditeur que de nombreux développeurs utilisent quotidiennement. Il est donc normal de vouloir l’utiliser pour écrire la documentation également. Sublime Text ne gère pas nativement le Markdown (hormis le fait que ce soit un éditeur de texte), en revanche il existe plusieurs plug-ins permettant d’éditer facilement et visuellement le Markdown.
Sublime Text est un éditeur de texte compatible avec les trois systèmes d’exploitation principaux, Linux, Mac OS et Windows.
Le plug-in Markdown Preview permet d’exporter facilement le contenu d’un fichier Markdown vers un fichier HTML. C’est un système très pratique pour versionner une documentation et partager une version plus lisible. Voir la page GitHub du produit : https://github.com/revolunet/sublimetext-markdown-preview
Le plug-in MarkdownEditing permet d’avoir une interface proposant la coloration syntaxique. Cette interface se montre plus intuitive et permet de faciliter la lecture de documents Markdown bruts.
Le plug-in MarkdownTOC (pour Markdown Table Of Content) permet d’éditer une table des matières en fonction des titres présents dans le document. L’un des avantages de ce plug-in est qu’après export en HTML (avec Markdown Preview), il est possible de cliquer sur un élément de la table des matières pour accéder à la section...
Configurer le dépôt local
Git nous offre de nombreuses options de configuration pour pouvoir le personnaliser selon notre utilisation.
Il existe plusieurs manières de configurer un dépôt local et il existe de nombreux paramètres. Nous aborderons donc dans l’ordre :
-
La configuration minimale d’un projet (sans cette configuration minimale, vous ne pourrez pas utiliser Git).
-
Les différents niveaux de configuration.
-
Les paramètres configurables.
-
La création et l’utilisation d’alias.
1. Configuration minimale
Cette configuration a déjà été évoquée à la fin du chapitre Installation de Git, à la section Configuration requise, cette partie sera donc très rapide. Pour utiliser Git, il est nécessaire de passer par une étape de configuration préalable. Sans celle-ci, il n’est pas possible d’utiliser Git normalement, il refusera par exemple d’enregistrer vos modifications.
Cette configuration va servir à nous identifier pour que Git sache qui effectue telle ou telle modification. Voici donc comment configurer sur le dépôt nos nom, prénom et adresse e-mail :
git config --global user.name "Prenom Nom"
git config --global user.email email@domain.ext
Maintenant que la configuration initiale a été définie, il est possible de travailler avec Git. Pour avoir une aide concernant la configuration et ses paramètres, il faut utiliser la commande suivante :
git config --help
2. Niveaux de configuration
Git utilise des fichiers pour stocker les différents éléments de configuration. Lorsque nous utilisons les commandes git config, ce sont indirectement ces fichiers que nous modifions.
Il existe trois niveaux de configuration dans Git. Ces niveaux de configuration ont tous une portée...
Les options de configuration avancées
Ces options de configuration ne sont pas particulièrement complexes, elles sont juste généralement moins utilisées que les précédentes et correspondent à des besoins plus précis.
1. Pagination
Lorsqu’on utilise des commandes comme git diff, si le résultat dépasse une page une pagination automatique sera effectuée à l’aide de less (commande UNIX affichant un texte page par page). Ce type de pagination peut déranger certains utilisateurs qui préféreraient n’avoir aucune pagination et naviguer sans contrainte dans le document. Pour cela, il faut définir une pagination de type cat :
git config --global pager = cat
2. Expressions régulières étendues
Par défaut, Git n’active pas les expressions régulières étendues, c’est-à-dire que les métacaractères comme les accolades sont totalement ignorés. Pour ceux qui sont habitués aux expressions régulières et qui les utilisent couramment, il est préférable d’activer l’option suivante :
git config --global extendedRegexp = true
3. Séparateur de mots
Lorsqu’on utilise git diff en mode mot (à l’aide de l’option --color-words par exemple), il peut être utile de spécifier à Git ce qu’est un mot. Par défaut, pour Git un mot est une suite de caractères séparée des autres par un ou des espaces. Or, dans une ligne de code il est possible de n’avoir aucun espace et pourtant certaines parties de la ligne sont sémantiquement différentes, c’est la raison pour laquelle il peut être utile de définir ce paramètre :
git config --global wordRegex = .{2}
En effet, ce paramètre...