# La ligne de commande

La ligne de commande, ou CLI pour *command line interface*, permet de piloter l'ordinateur en tapant du texte. Tous les autres cours de cette partie s'appuient dessus : installer un outil, se connecter à un serveur, lancer un conteneur.

:::info{title="Quel terminal ?"}

Les commandes de ce cours sont celles de macOS et de Linux. Sous Windows, le plus simple est d'installer WSL, qui donne un vrai terminal Linux, ou d'utiliser Git Bash.

:::

## Le problème

Le `README.md` du projet tient en deux lignes :

```text
pip freeze > requirements.txt
pip install -f requirements.txt
```

Pour s'en servir, il faut déjà savoir où taper ces lignes, depuis quel dossier, ce que fait le signe `>`, et ce qu'est une option comme `-f`. Rien de tout cela n'est écrit.

Deuxième exemple : le jeu se lance avec `python src/main.py`, mais seulement depuis la racine du projet. Il cherche ses images dans `assets`, un chemin **relatif au dossier courant** (`ASSETS_PATH = "assets"` dans `constants.py`). La notion de dossier courant ne se voit pas dans un éditeur. Elle se comprend au terminal.

## Terminal, shell, commande

Trois mots qu'on confond souvent.

<Mermaid
  chart={`flowchart LR
    user([Vous]) -- tapez du texte --> term[Terminal<br/>la fenêtre]
    term --> shell[Shell<br/>zsh ou bash, il lit la ligne]
    shell --> prog[Programme<br/>ls, python, git]
    prog -- affiche le résultat --> term`}
/>

| Mot | Ce que c'est |
| --- | --- |
| Terminal | La fenêtre dans laquelle on tape |
| Shell | Le programme qui lit la ligne et lance la commande. `zsh` sur macOS, `bash` sur la plupart des Linux |
| Commande | Un programme, suivi de ce qu'on lui donne |
| Invite | Le texte affiché avant le curseur, qui se termine souvent par `$` ou `%` |

## Anatomie d'une commande

```bash
grep -n --color "self.game" src/units.py
```

| Morceau | Nom | Rôle |
| --- | --- | --- |
| `grep` | Programme | Ce qu'on lance : ici, un outil de recherche de texte |
| `-n` | Option courte | Un tiret, une lettre : afficher les numéros de ligne |
| `--color` | Option longue | Deux tirets, un mot : colorer ce qui est trouvé |
| `"self.game"` | Argument | Le texte cherché |
| `src/units.py` | Argument | Le fichier dans lequel chercher |

Pour savoir ce qu'accepte une commande : `man grep` ouvre son manuel, qu'on quitte avec la touche `q`. Beaucoup d'outils répondent aussi à `--help`, par exemple `python3 --help` ou `git --help`.

## Se repérer et se déplacer

Le terminal est toujours « dans » un dossier : le **dossier courant**.

| Commande | Effet |
| --- | --- |
| `pwd` | Affiche le dossier courant |
| `ls` | Liste son contenu |
| `ls -la` | Liste détaillée, fichiers cachés compris |
| `cd src` | Entre dans `src` |
| `cd ..` | Remonte d'un niveau |
| `cd ~` | Retourne dans le dossier personnel |
| `cd -` | Retourne dans le dossier précédent |

### Chemins absolus et relatifs

Un chemin **absolu** part de la racine du disque et commence par `/`. Il désigne le même endroit quel que soit le dossier courant. Un chemin **relatif** part du dossier courant.

| Écriture | Sens |
| --- | --- |
| `/Users/alice/BestGameOfTheYear` | Chemin absolu |
| `src/main.py` | Relatif : le fichier `main.py` dans le dossier `src` d'ici |
| `.` | Le dossier courant |
| `..` | Le dossier parent |
| `~` | Le dossier personnel |

C'est ce qui explique le comportement du jeu :

```bash
cd BestGameOfTheYear
python src/main.py      # le dossier courant contient assets/ : ça marche

cd src
python main.py          # le dossier courant est src/ : assets/ est introuvable
```

## Manipuler des fichiers

| Commande | Effet |
| --- | --- |
| `mkdir tests` | Crée un dossier |
| `touch tests/test_hex.py` | Crée un fichier vide |
| `cp a.py b.py` | Copie |
| `mv a.py b.py` | Déplace ou renomme |
| `rm a.py` | Supprime un fichier |
| `rm -r dossier` | Supprime un dossier et son contenu |

:::danger{title="rm ne passe pas par la corbeille"}

Un fichier supprimé avec `rm` est perdu. Avant un `rm -r`, on vérifie le dossier courant avec `pwd` et on relit la ligne. Un projet suivi par Git limite les dégâts : ce qui a été commité se retrouve.

:::

## Lire et chercher

| Commande | Effet |
| --- | --- |
| `cat requirements.txt` | Affiche tout le fichier |
| `head -20 src/ui.py` | Les 20 premières lignes |
| `tail -20 src/ui.py` | Les 20 dernières |
| `less src/ui.py` | Lecture page par page, `q` pour quitter |
| `wc -l src/*.py` | Compte les lignes de chaque fichier |
| `grep -n "self.game" src/units.py` | Les lignes qui contiennent ce texte, avec leur numéro |
| `grep -rn "selected_tile" src` | Même recherche dans tout un dossier |

`grep` est l'outil qui a servi à l'audit : compter combien de fonctions écrivent dans `selected_tile` se fait en une ligne.

## Enchaîner les commandes

Deux mécanismes donnent sa puissance au terminal.

**La redirection** envoie le résultat d'une commande dans un fichier.

| Écriture | Effet |
| --- | --- |
| `commande > fichier` | Écrit le résultat dans le fichier, en l'écrasant |
| `commande >> fichier` | Ajoute à la fin du fichier |

La première ligne du README se lit donc ainsi : `pip freeze` affiche la liste des paquets installés, et `>` l'écrit dans `requirements.txt`.

**Le tube**, noté par une barre verticale, donne le résultat d'une commande à la suivante.

```bash
grep -rn "self.game" src | wc -l
```

`grep` trouve toutes les lignes, `wc -l` les compte. Aucune des deux commandes ne connaît l'autre.

<Mermaid
  chart={`flowchart LR
    a[grep -rn self.game src] -- les lignes trouvées --> b[wc -l]
    b --> c([un nombre])`}
/>

## Les variables d'environnement

Le shell garde des variables, que les programmes lancés peuvent lire.

```bash
echo $HOME          # afficher une variable
export DEBUG=1      # en créer une pour la session
```

La plus importante est `PATH` : la liste des dossiers dans lesquels le shell cherche les programmes. Quand le terminal répond `command not found`, c'est que le programme n'est dans aucun de ces dossiers.

```bash
which python3       # dit quel fichier sera lancé
```

## L'environnement virtuel Python

Un environnement virtuel est un dossier qui contient un Python et des paquets propres à un projet. Sans lui, tous les projets de la machine partagent les mêmes paquets, et les versions finissent par se gêner.

```bash
python3 -m venv .venv            # créer l'environnement, une seule fois
source .venv/bin/activate        # l'activer, à chaque nouveau terminal
pip install -r requirements.txt  # installer les paquets du projet
python src/main.py               # lancer le jeu
deactivate                       # en sortir
```

« Activer » ne fait qu'une chose : placer `.venv/bin` en tête de `PATH`. `which python` le montre avant et après.

## Aller plus vite

| Touche | Effet |
| --- | --- |
| Tab | Complète le nom d'un fichier ou d'une commande |
| Flèche haut | Rappelle la commande précédente |
| Ctrl + R | Cherche dans l'historique |
| Ctrl + C | Arrête le programme en cours |
| Ctrl + L | Efface l'écran |
| Ctrl + D | Ferme le shell |

La touche Tab évite la plupart des fautes de frappe dans les chemins. Si elle ne complète rien, c'est souvent que le chemin est faux.

## Lire un message d'erreur

| Message | Cause probable |
| --- | --- |
| `command not found` | Programme non installé, ou absent de `PATH` |
| `No such file or directory` | Chemin faux, ou mauvais dossier courant |
| `Permission denied` | Pas le droit de lire, d'écrire ou d'exécuter |
| `ModuleNotFoundError` | Environnement virtuel non activé, ou paquet non installé |

## À retenir

- Une commande : un programme, des options, des arguments.
- Le terminal est toujours dans un dossier, et les chemins relatifs en dépendent.
- `>` écrit dans un fichier, le tube relie deux commandes.
- `PATH` décide quel programme est lancé.
- Un environnement virtuel par projet.

## Exercices

1. Depuis la racine du projet, afficher le nombre de lignes de chaque fichier de `src`, puis seulement le total.
2. Compter les lignes de `src/ui.py` qui contiennent `page == 5`.
3. Créer un environnement virtuel, installer les dépendances, lancer le jeu. Comparer `which python` avant et après l'activation.
4. Lancer le jeu depuis `src`, lire l'erreur, et expliquer d'où elle vient.
5. Écrire dans `lignes.txt` la liste des fichiers de `src` avec leur nombre de lignes, sans ouvrir d'éditeur.
