Configuration de projet

Lancez lazyshell dans un dossier contenant un lazyshell.yml et il démarre les sessions que ce fichier déclare — chacune dans son répertoire, avec son environnement et sa commande — au lieu de s'ouvrir vide.

Principe

lazyshell init écrit un point de départ commenté dans le répertoire courant. Les sessions démarrent dans l'ordre du fichier, et la première est sélectionnée. Une entrée qui ne valide pas (name vide ou dupliqué, cwd manquant) est ignorée et signalée dans la barre d'état — les autres démarrent quand même.

Exemple

# ./lazyshell.yml

# Optionnel : surcharge le shell de la config utilisateur, pour ce projet seulement.
shell: /bin/zsh

# Optionnel : fichiers .env chargés pour toutes les sessions ci-dessous, dans
# l'ordre — un fichier plus loin surcharge une clé posée par un précédent.
env_files:
  - .env
  - .env.local

# Optionnel : déclare les groupes utilisés par ce projet et — la seule raison
# d'écrire ce bloc — l'ordre de leurs en-têtes dans le panneau des sessions.
groups:
  - name: services
  - name: agents

sessions:
  - name: api
    # Optionnel : le groupe de démarrage. Modifiable ensuite avec « g ».
    group: services
    # Relatif à *ce fichier*, pas au dossier depuis lequel vous avez lancé
    # lazyshell. « ~ » est développé. Absent, il vaut le dossier de ce fichier.
    cwd: ./services/api
    # Tapée dans le shell une fois qu'il est prêt, pas exécutée à sa place :
    # quand la commande se termine (ou que vous faites Ctrl-C), le shell est
    # toujours là.
    command: make dev
    env:
      PORT: "3000"
    # Optionnel : en plus des env_files ci-dessus, pour cette session seulement.
    env_files:
      - .env.api
    # Optionnel : notifie quand une ligne correspond. « v » en arme un à la volée.
    watch:
      - pattern: "ERR!"
        notify: true
    # Optionnel : never (défaut) | on-failure | always. Redémarre le shell
    # automatiquement quand la commande se termine, avec un délai qui double
    # à chaque tentative consécutive (1s, 2s, 4s... plafonné à 60s) et se
    # réinitialise dès qu'un redémarrage tient 10s. « R » (ou « W » pour le
    # groupe) redémarre tout de suite, sans attendre.
    restart: on-failure
    # Optionnel, faux par défaut. Quand la commande se termine avec un code non
    # nul, tue la session directement au lieu de laisser le shell ouvert en
    # dessous — l'inverse du comportement par défaut ci-dessus. Sans effet
    # sans commande : il n'y a rien à surveiller.
    stop_on_failure: false
    # Optionnel. Une session qui déclare une `command:` démarre *verrouillée* —
    # vous voyez sa sortie, vos touches ne lui parviennent pas, donc un Ctrl-C
    # parti de travers ne peut pas la tuer. À déclarer pour surcharger :
    # `false` pour pouvoir y taper tout de suite, `true` pour verrouiller un
    # simple shell.
    locked: false

  - name: web
    group: services
    cwd: ./web
    command: npm run dev

  - name: shell          # sans groupe : affichée sous « sans groupe », en bas

Une session qui déclare une command: démarre verrouillée, sauf si elle dit locked: false. Verrouillée veut dire que le panneau de sortie l'affiche mais ne lui transmet pas vos frappes : on peut défiler, chercher et copier, et un q mal tapé ou un Ctrl-C destiné à autre chose ne peut pas tuer la commande. i ou Entrée reprend le clavier, la touche préfixe (Ctrl-O) ou Échap Échap le rend — et lazyshell mémorise, par session, le dernier choix, si bien que parcourir la liste avec j/k vous dépose dans l'état où chaque session a été laissée. Un simple shell ne déclare pas de commande : il démarre donc prêt à la saisie.

Les groupes sont un regroupement d'affichage — voir Groupes. En déclarer un ici est facultatif et ne fixe que l'ordre des en-têtes : une session peut citer un groupe absent de ce bloc, il se place simplement après les groupes déclarés. Une mauvaise entrée de groups: (name vide ou dupliqué) est écartée et signalée comme une mauvaise session, et les autres s'appliquent quand même.

Référence des champs

Ce qui est lu, ce qui ne l'est pas

Fichiers .env

Toute session — déclarée dans un fichier de projet ou non — charge automatiquement un .env depuis son propre répertoire de travail, s'il y en a un. Par-dessus, chaque couche surcharge celle d'avant :

1. <cwd de la session>/.env, automatique, sauf désactivation (voir plus bas)
2. --env-file <chemin> (répétable, s'applique à toutes les sessions démarrées par ce lancement)
3. les env_files: du projet (toutes les sessions déclarées)
4. les env_files: d'une session (cette session seulement)
5. la table env: de cette session — elle gagne toujours, sur tous les fichiers

Pour couper la recherche automatique de <cwd>/.env :

• --no-env-file — toutes les sessions démarrées par ce lancement ;
• no_default_env: true en tête d'un fichier de projet — toutes les sessions qu'il déclare ;
• ou sur une seule entrée de session — cette session seulement, ce qui surcharge le réglage du projet dans un sens comme dans l'autre.

Quel fichier est utilisé

1. --config-file <fichier> (-f)
2. $LAZYSHELL_PROJECT_CONFIG
3. ./lazyshell.yml
4. ./.lazyshell.yml

Seul le répertoire courant est fouillé — pas de remontée jusqu'à la racine du dépôt, de sorte que le fichier qui s'exécute est toujours celui que vous voyez.

Approuver un fichier de projet

Un lazyshell.yml est versionné dans un dépôt : sans garde-fou, il exécuterait des commandes arbitraires à la seconde où vous entrez dans un clone. lazyshell demande donc une fois, avant l'ouverture de l'interface, et retient la réponse par fichier — puis redemande dès que le contenu du fichier change.

$ lazyshell allow            # approuve le fichier du dossier courant, sans rien lancer
$ lazyshell allow ./x.yml    # approuve un fichier précis
$ lazyshell --no-autostart   # ouvre l'interface sans rien démarrer
$ lazyshell --env-file .env.prod   # fichier .env supplémentaire, pour ce lancement
$ lazyshell --no-env-file          # ignore le « <cwd>/.env » automatique

Les approbations vivent dans un trust.yml à côté de votre configuration utilisateur. Quand l'entrée standard n'est pas un terminal, l'approbation est refusée plutôt que supposée.

Persistance de la disposition

À la fermeture, lazyshell enregistre pour le répertoire courant le nom, le groupe, le répertoire de travail et la commande de lancement de chaque session dans ~/.config/lazyshell/state/<hash-du-répertoire>.yml — pas ce qui se passe en direct dans le shell, seulement la recette avec laquelle il a démarré. Relancez depuis ce même répertoire sans lazyshell.yml présent, et lazyshell propose de restaurer cette disposition à la place de l'unique session par défaut habituelle.

restore_layout contrôle ce que « propose » veut dire : ask (défaut) affiche une popup de confirmation nommant les sessions qui seraient recréées ; always les restaure sans la montrer ; never ne la propose jamais, mais la disposition continue d'être enregistrée quand même — repasser à ask/always plus tard la retrouve donc intacte. Refuser la popup laisse la liste de sessions vide, exactement là où vous laisse --no-autostart, avec n à portée de main pour en démarrer une à la main.

Un lazyshell.yml présent dans le répertoire l'emporte toujours : ce sont ses sessions déclarées qui démarrent, et la disposition enregistrée n'est même pas lue — seulement tenue à jour au cas où le fichier serait retiré plus tard.