Guide GitHub CLI pour Jnane¶

🚀 Introduction¶

GitHub CLI (gh) est l'outil officiel en ligne de commande pour interagir avec GitHub. Ce guide montre comment l'utiliser pour gérer les features et issues du projet Jnane.

📦 Installation¶

Windows¶

# Avec winget
winget install GitHub.cli

# Avec Chocolatey
choco install gh

# Avec Scoop
scoop install gh

macOS¶

brew install gh

Linux¶

# Debian/Ubuntu
sudo apt install gh

# Fedora/CentOS
sudo dnf install gh

# Arch Linux
sudo pacman -S github-cli

Vérification¶

gh --version
# gh version 2.40.0 (ou supérieur)

🔐 Authentification¶

gh auth login

Sélectionner : 1. GitHub.com (pas GitHub Enterprise) 2. HTTPS comme protocole 3. Authenticate Git with your GitHub credentials → Yes 4. Login with a web browser (recommandé)

Copier le code affiché et ouvrir le navigateur automatiquement.

Vérifier l'Authentification¶

gh auth status

# Résultat attendu :
# ✓ Logged in to github.com as YOUR_USERNAME

Se Déconnecter¶

gh auth logout

📋 Gestion des Issues¶

Lister les Issues¶

# Toutes les issues
gh issue list

# Limiter le nombre
gh issue list --limit 20

# Issues ouvertes uniquement
gh issue list --state open

# Issues fermées
gh issue list --state closed

# Filtrer par label
gh issue list --label feature
gh issue list --label "status: implemented"

# Filtrer par assigné
gh issue list --assignee @me

# Recherche
gh issue list --search "named arguments"

Voir une Issue¶

# Dans le terminal
gh issue view 123

# Dans le navigateur
gh issue view 123 --web

Créer une Issue¶

# Mode interactif
gh issue create

# Mode direct
gh issue create \
  --title "[FEAT-009] Named Arguments" \
  --body "Feature specification for named arguments" \
  --label "feature,status: implemented"

# Avec un template
gh issue create \
  --template feature_implementation.md \
  --title "[FEAT-009] Named Arguments"

# Depuis un fichier
gh issue create \
  --title "[FEAT-009] Named Arguments" \
  --body-file issue_body.md

Éditer une Issue¶

# Mode interactif
gh issue edit 123

# Changer le titre
gh issue edit 123 --title "Nouveau titre"

# Ajouter des labels
gh issue edit 123 --add-label "priority: high"

# Retirer des labels
gh issue edit 123 --remove-label "status: planned"

# Assigner
gh issue edit 123 --add-assignee @me

# Ajouter à un milestone
gh issue edit 123 --milestone "v1.0"

Commenter une Issue¶

# Ajouter un commentaire
gh issue comment 123 --body "Commentaire ici"

# Depuis un fichier
gh issue comment 123 --body-file comment.md

Fermer/Réouvrir une Issue¶

# Fermer
gh issue close 123

# Fermer avec commentaire
gh issue close 123 --comment "Implémenté dans v1.0"

# Réouvrir
gh issue reopen 123

Supprimer une Issue¶

gh issue delete 123

🏷️ Labels¶

Lister les Labels¶

gh label list

Créer un Label¶

gh label create "status: implemented" \
  --description "Feature implemented" \
  --color "28a745"

gh label create "maturity: high" \
  --description "High maturity (≥4.0)" \
  --color "0e8a16"

Éditer un Label¶

gh label edit "status: implemented" \
  --name "status: done" \
  --color "0e8a16"

Supprimer un Label¶

gh label delete "old-label"

🎯 Milestones¶

Lister les Milestones¶

gh api repos/:owner/:repo/milestones

Créer un Milestone¶

gh api repos/:owner/:repo/milestones \
  --method POST \
  --field title="v1.0.0" \
  --field description="First release" \
  --field due_on="2025-12-31T23:59:59Z"

🔍 Recherche Avancée¶

Rechercher des Issues¶

# Issues feature implémentées
gh issue list --search "label:feature label:\"status: implemented\""

# Issues ouvertes avec haute maturité
gh issue list --search "is:open label:\"maturity: high\""

# Issues syntaxe
gh issue list --search "label:\"area: syntax\""

# Issues créées cette semaine
gh issue list --search "created:>=$(date -d '7 days ago' +%Y-%m-%d)"

# Issues assignées à moi
gh issue list --search "assignee:@me"

🤖 Automatisation avec Scripts¶

Script PowerShell : Créer Issues en Masse¶

# create_features_issues.ps1

# Tableau des features à créer
$features = @(
    @{id="FEAT-009"; title="Named Arguments"; labels="feature,status: implemented,area: syntax"},
    @{id="FEAT-030"; title="Views System"; labels="feature,status: implemented,area: types"},
    @{id="FEAT-044"; title="Control Structures"; labels="feature,status: implemented,area: control"}
)

foreach ($feat in $features) {
    Write-Host "Creating issue for $($feat.id)..."

    gh issue create `
        --title "[$($feat.id)] $($feat.title)" `
        --body "Feature spec: $($feat.id)" `
        --label $feat.labels

    Start-Sleep -Seconds 2  # Éviter rate limiting
}

Write-Host "Done! Created $($features.Count) issues."

Script Bash : Sync Labels¶

#!/bin/bash
# sync_labels.sh

# Labels de statut
gh label create "status: implemented" --color "28a745" -f
gh label create "status: in-progress" --color "007bff" -f
gh label create "status: planned" --color "ffc107" -f
gh label create "status: blocked" --color "dc3545" -f

# Labels de maturité
gh label create "maturity: high" --color "0e8a16" -f
gh label create "maturity: medium" --color "fbca04" -f
gh label create "maturity: low" --color "d93f0b" -f

# Labels d'area
gh label create "area: syntax" --color "5319e7" -f
gh label create "area: types" --color "0052cc" -f
gh label create "area: control" --color "006b75" -f
gh label create "area: aspects" --color "c5def5" -f

echo "✅ Labels synchronized!"

🔗 Intégration avec le Système de Ticketing Jnane¶

Créer Issues depuis les Specs¶

Le projet Jnane fournit un script pour générer automatiquement les commandes gh :

# Générer les commandes
python scripts/generate_gh_commands.py

# Résultat : scripts/create_issues.ps1 avec 127 commandes

# Exécuter
powershell -File scripts/create_issues.ps1

Workflow Typique¶

# 1. Lister features sans issue
python scripts/sync_github_issues.py --dry-run

# 2. Créer les issues manquantes
python scripts/generate_gh_commands.py
powershell -File scripts/create_issues.ps1

# 3. Vérifier
gh issue list --label feature --limit 20

# 4. Mettre à jour une feature
gh issue edit 123 --add-label "status: implemented"

📊 Rapports et Statistiques¶

Issues par Label¶

# Count issues par label
gh issue list --label feature --json number | jq '. | length'

# Implemented features
gh issue list --search "label:feature label:\"status: implemented\"" --json number | jq '. | length'

# In progress
gh issue list --search "label:feature label:\"status: in-progress\" is:open" --json number | jq '. | length'

Exporter en CSV¶

gh issue list --limit 1000 --json number,title,state,labels,createdAt \
  | jq -r '.[] | [.number, .title, .state, (.labels | map(.name) | join(",")), .createdAt] | @csv' \
  > issues.csv

Dashboard dans le Terminal¶

# Issues summary
echo "=== Issues Summary ==="
echo "Total: $(gh issue list --limit 1000 --json number | jq '. | length')"
echo "Open: $(gh issue list --state open --json number | jq '. | length')"
echo "Closed: $(gh issue list --state closed --json number | jq '. | length')"
echo ""
echo "=== By Status ==="
echo "Implemented: $(gh issue list --search 'label:\"status: implemented\"' --json number | jq '. | length')"
echo "In Progress: $(gh issue list --search 'label:\"status: in-progress\"' --json number | jq '. | length')"
echo "Planned: $(gh issue list --search 'label:\"status: planned\"' --json number | jq '. | length')"

🎨 Personnalisation¶

Alias GitHub CLI¶

Ajouter dans votre shell config (.bashrc, .zshrc, $PROFILE) :

# PowerShell
function ghi { gh issue list $args }
function ghiv { gh issue view $args }
function ghic { gh issue create $args }
function ghie { gh issue edit $args }

# Bash/Zsh
alias ghi='gh issue list'
alias ghiv='gh issue view'
alias ghic='gh issue create'
alias ghie='gh issue edit'

Configuration gh¶

# Éditeur par défaut
gh config set editor "code"  # VS Code
gh config set editor "vim"   # Vim

# Browser par défaut
gh config set browser "chrome"

# Pager
gh config set pager "less"

🔥 Commandes Avancées¶

Créer une Issue avec Checklist¶

gh issue create \
  --title "[FEAT-009] Named Arguments" \
  --body "## Implementation Checklist

- [ ] Spec completed
- [ ] Core implementation
- [ ] Unit tests
- [ ] Documentation
- [ ] Samples

Refs: FEAT-009"

Bulk Operations¶

# Fermer toutes les issues d'un milestone
gh issue list --milestone "v1.0" --json number -q '.[].number' \
  | xargs -I {} gh issue close {}

# Ajouter label à toutes les features
gh issue list --search "label:feature" --json number -q '.[].number' \
  | xargs -I {} gh issue edit {} --add-label "project: jnane"

API REST Directe¶

# GET issues
gh api repos/gregoirerichard/jnane.lang/issues

# POST nouvelle issue
gh api repos/gregoirerichard/jnane.lang/issues \
  --method POST \
  --field title="Test Issue" \
  --field body="Description" \
  --field labels='["feature"]'

# PATCH modifier issue
gh api repos/gregoirerichard/jnane.lang/issues/123 \
  --method PATCH \
  --field state="closed"

📚 Ressources¶

Documentation Officielle¶

Jnane Specific¶

💡 Astuces¶

Recherche Rapide¶

# Feature par ID
gh issue list --search "FEAT-009 in:title"

# Issues récentes
gh issue list --search "created:>2025-10-01"

# Issues populaires (beaucoup de commentaires)
gh issue list --search "comments:>5"

Format de Sortie¶

# JSON
gh issue list --json number,title,state

# Template personnalisé (utilise les accolades Go template)
gh issue list --template '{{range .}}{{.number}}: {{.title}}{{"\n"}}{{end}}'

# Pipe vers jq
gh issue list --json number,title,labels | jq '.[] | select(.labels[].name == "feature")'

Notifications¶

# Lister notifications
gh api notifications

# Marquer comme lu
gh api notifications/threads/THREAD_ID \
  --method PATCH

Dernière mise à jour : 26 octobre 2025
Maintenu par : Équipe Jnane