GitJournal

Application Electron pour générer un journal de travail à partir des commits Git locaux et des commentaires d'issues GitHub.

Le même moteur est disponible en ligne de commande et comme GitHub Action, pour tenir un journal.md à jour automatiquement (voir Journal automatique avec GitHub Actions).

Première utilisation

1. Installer les dépendances

cd src
pnpm install

2. Lancer l'application

pnpm start

Utilisation

Créer un nouveau projet

1. Menu : Fichier > Nouveau projet (Cmd+N / Ctrl+N)
2. Choisir où sauvegarder le fichier .gitj — le placer à la racine du dépôt git à analyser
3. Remplir le formulaire :
   • Nom du projet : affiché dans le journal et l'export
   • Nom(s) d'utilisateur Git : valeur(s) qui apparaissent dans git log --author=… (filtre vos commits). Séparer plusieurs noms par une virgule ou un point-virgule.
   • Date de début : optionnel, ignore les commits antérieurs

L'application utilise le dossier du fichier .gitj comme racine du dépôt git. L'URL GitHub (pour les liens de commits) est détectée automatiquement via git remote get-url origin.

Format du fichier .gitj

{
  "projectName": "Mon Projet",
  "me": ["Prénom Nom", "username"],
  "journalStartDate": "2024-01-01T00:00:00.000Z",
  "columns": [
    { "label": "Date", "source": "date", "format": "date", "field": "date" },
    { "label": "Tâche", "source": "name", "field": "name" },
    { "label": "Activité", "source": "activity", "field": "activity", "type": "select", "values": ["dev", "spec", "GP"] },
    { "label": "Description", "source": "description", "field": "description" },
    { "label": "Durée", "source": "duration", "format": "duration", "field": "duration" },
    { "label": "Statut", "source": "status", "format": "badge", "field": "status" },
    { "label": "Auteur", "source": "author" }
  ],
  "exceptions": []
}

Champ	Obligatoire	Description
projectName	oui	Nom affiché dans le journal
me	oui	Nom d'auteur git, ou liste de noms, pour filtrer vos commits
journalStartDate	non	Date de début, format ISO 8601
columns	oui	Colonnes affichées dans le journal
exceptions	oui	Entrées manuelles et modifications de commits
includeIssues	non	true pour ajouter les commentaires d'issues dans l'application (défaut : false)
githubUsers	non	Logins GitHub supplémentaires pour filtrer les commentaires d'issues

L'application scanne toutes les branches automatiquement (git log --all).

Colonnes personnalisées

La propriété columns permet d'ajouter des colonnes au journal. Pour une colonne personnalisée éditable, utiliser le même nom libre dans source et field :

{ "label": "Activité", "source": "activity", "field": "activity" }

Pour afficher une liste déroulante dans le formulaire d'ajout ou de modification, ajouter type: "select" ou type: "dropdown" avec les valeurs autorisées :

{ "label": "Activité", "source": "activity", "field": "activity", "type": "select", "values": ["dev", "spec", "GP"] }

options peut aussi être utilisé à la place de values.

Ouvrir un projet existant

Menu : Fichier > Ouvrir projet (Cmd+O / Ctrl+O)

Format des messages de commit

L'application extrait les métadonnées entre crochets n'importe où dans le message :

feat: add login [30m done]

ou sur une ligne séparée :

feat: add login
[30m done]
Description détaillée...

Format compact (crochet unique) :

Syntaxe	Résultat
[2h30] ou [2h30m]	2h30
[45m]	45 minutes
[1h]	1 heure
[5]	5 minutes (unité implicite)
[2h30 done]	2h30, statut Done
[45m wip]	45 min, statut WIP

Format classique (multi-crochets) :

Syntaxe	Résultat
[2][30]	2h30
[90]	90 minutes
[Done] / [WIP]	statut

Commentaires d'issues

Les commentaires d'issues et de pull requests suivent le même formalisme que les commits :

[45m done] Tests concluants sur la régulation

Seuls les crochets commençant par un chiffre sont reconnus dans les commentaires, pour ne pas confondre les métadonnées avec les liens [texte](url) ou les cases à cocher - [x].

Contrairement aux commits, tous les commentaires sont inclus, même sans durée : le journal sert aussi à retrouver ce qui a été discuté.

Les commentaires sont filtrés par auteur : leur login GitHub doit figurer dans me ou dans githubUsers (sans .gitj, tous les auteurs sont pris en compte).

Dans l'application, activer "includeIssues": true dans le .gitj. Le token GitHub se définit dans Préférences (token fine-grained avec la permission Issues : Read-only) ; à défaut, il est lu dans GH_TOKEN / GITHUB_TOKEN, puis via gh auth token (GitHub CLI). Un dépôt public fonctionne sans token, dans la limite de 60 requêtes par heure.

Les commentaires ne peuvent pas être modifiés ni exclus dans GitJournal (les exceptions du .gitj ne s'appliquent qu'aux commits) : pour corriger un commentaire, le modifier sur GitHub.

Ajouter une entrée manuelle

1. Cliquer sur le bouton + en bas du tableau
2. Remplir le formulaire (nom, description, date, durée en minutes, statut)
3. Cliquer sur Enregistrer

Modifier ou exclure une entrée

Cliquer sur une ligne du tableau pour ouvrir le formulaire de modification.

• Enregistrer : sauvegarde les modifications
• Exclure : retire un commit du journal (sans le supprimer de Git)
• Supprimer : supprime une entrée manuelle

Exporter

Action	Raccourci
Exporter en PDF	Cmd+E / Ctrl+E
Exporter en CSV	Cmd+Shift+E / Ctrl+Shift+E
Imprimer	Cmd+P / Ctrl+P

Le CSV contient une colonne supplémentaire "Tâche (abrégé)" : texte extrait du nom du commit avant la première parenthèse ouvrante.

Sauvegarder

Menu : Fichier > Enregistrer (Cmd+S / Ctrl+S)

Les modifications sont aussi sauvegardées automatiquement après chaque ajout ou modification.

Journal automatique avec GitHub Actions

GitJournal peut générer un journal Markdown dans le dépôt à journaliser, à chaque push (toutes branches), à chaque commentaire ou modification d'issue, ou manuellement.

Copier doc/journal-workflow.yml dans .github/workflows/journal.yml du dépôt à journaliser. Le journal :

• rassemble les commits de toutes les branches (dédupliqués par SHA, avec le nom de la branche) et les commentaires d'issues ;
• est regroupé par jour (fuseau Europe/Zurich), du plus récent au plus ancien ;
• est écrit sur la branche par défaut, même quand le push concerne develop. Si main exige des pull requests, ajouter GitHub Actions aux exceptions (Bypass list) de la règle, ou écrire le journal sur une branche dédiée avec branch: journal ;
• utilise le .gitj à la racine du dépôt s'il existe (filtre d'auteur, date de début, exclusions de commits, entrées manuelles).

Le commit du journal est fait avec GITHUB_TOKEN, il ne redéclenche donc pas le workflow.

Paramètres de l'action (with:) :

Paramètre	Défaut	Description
output	nom du .gitj en .md (journal.md sans .gitj)	Fichier généré
gitj	premier *.gitj à la racine	Configuration à utiliser
timezone	Europe/Zurich	Fuseau pour le regroupement par jour
issues	true	Inclure les commentaires d'issues
commit	true	Committer et pousser le journal
branch	branche extraite	Branche où committer le journal (créée si absente)
commit-message	docs: update work journal	Message du commit

En ligne de commande

node src/cli.js --repo ../mon-depot --output - # affiche le journal
node src/cli.js --help

Raccourcis clavier

Raccourci	Action
Cmd/Ctrl + N	Nouveau projet
Cmd/Ctrl + O	Ouvrir projet
Cmd/Ctrl + S	Enregistrer
Cmd/Ctrl + E	Exporter en PDF
Cmd/Ctrl + Shift + E	Exporter en CSV
Cmd/Ctrl + P	Imprimer
Cmd/Ctrl + R	Actualiser
Cmd/Ctrl + +/-	Zoom

Versionner vos projets

Les fichiers .gitj peuvent être versionnés avec Git :

git add mon-projet.gitj
git commit -m "Mise à jour du journal"
git push

Développement et build

Voir src/BUILD.md pour les instructions détaillées.

cd src
pnpm dev          # mode développement (DevTools ouvert)
pnpm test         # lancer les tests
pnpm build        # build pour la plateforme courante
pnpm build:mac    # .dmg macOS
pnpm build:win    # .exe Windows
pnpm build:linux  # .AppImage / .deb Linux

Les artefacts sont générés dans src/dist/.

Structure du projet

src/
├── main.js                 # Main process Electron
├── cli.js                  # Génération Markdown en ligne de commande (GitHub Action)
├── preload.js              # Bridge IPC sécurisé
├── version.js              # Numéro de version
├── package.json
├── assets/                 # Icônes de l'application
└── server/
    ├── server.js           # Serveur Express interne
    ├── lib/
    │   ├── commit-parser.js    # Parsing des métadonnées (commits et commentaires)
    │   ├── issue-reader.js     # Lecture des commentaires d'issues (API GitHub)
    │   ├── journal-generator.js # Collecte des entrées (commits, issues, exceptions)
    │   ├── markdown-export.js  # Rendu du journal Markdown
    │   ├── gitj-manager.js     # Lecture/écriture des fichiers .gitj
    │   └── settings-manager.js # Persistance des préférences
    └── views/              # Templates EJS

Dépannage

L'app ne démarre pas

• Vérifier que les dépendances sont installées (pnpm install dans src/)
• Consulter les logs dans la console de développement (pnpm dev)

Le journal est vide

• Vérifier que le fichier .gitj est bien placé à la racine du dépôt git
• Vérifier que le champ me correspond exactement au nom d'auteur dans vos commits (git log --author=…)
• Vérifier que vos commits contiennent une durée entre crochets

Pas de liens GitHub dans le tableau

• Vérifier que le dépôt a un remote origin pointant vers GitHub (git remote -v)

Support

Pour rapporter un bug ou demander une fonctionnalité, créer une issue sur GitHub.