La línea de órdenes

El binario acepta estas opciones y ningún subcomando. Todo lo demás está en el fichero de configuración, porque un horario no es algo que se reescriba a mano.

ghchronicle -config /etc/ghchronicle/config.yaml

Todas las opciones

Opción	Por omisión	Qué hace
`-setup`	off	Pregunta lo que necesita una configuración que funcione, comprueba cada respuesta contra aquello que nombra, y la escribe
`-config`	`config.yaml`	Ruta del fichero de configuración
`-once`	apagada	Hace una pasada y sale en vez de quedarse programando; una familia a la que no le toca por cadencia se salta igual
`-list`	apagada	Imprime los repositorios que se recogerían, y cuáles quedan aparte, y sale
`-version`	apagada	Imprime la versión, el commit y la fecha de compilación, y sale
`-groups`	apagada	Imprime los grupos con las familias de cada uno, y sale
`-backfill`	apagada	Llega tan atrás como permita cada superficie, esperando a que se reponga el límite en vez de parar
`-backfill-since`	ninguno	Acota el relleno: una fecha (`2024-01-01`), una duración (`720h`), días (`90d`) o años (`2y`)
`-backfill-status`	apagada	Imprime hasta dónde han llegado el relleno en curso y la relectura de una migración, y sale; no pregunta nada a GitHub, no escribe nada y no necesita token
`-backfill-retry`	`0`	Cuando un relleno, o la relectura de una migración, acaba con familias pendientes, espera esto y vuelve a por ellas, hasta que una pasada no anote nada nuevo; `0` no vuelve
`-families`	ninguno	Con `-backfill`, recorre solo estas familias, separadas por comas, los nombres que imprime `-groups`; un nombre que no es una familia, o la opción sin `-backfill`, se rechaza con 2
`-publish-dashboard`	off	Publica el dashboard de Grafana y el datasource del que lee, y sale; necesita la sección `grafana`, no le pregunta nada a GitHub y no necesita token
`-uninstall`	ninguno	Quita lo que esto puso y sale: `dashboard`, `data`, `state`, `all`, separados por comas; lista y no quita nada sin `-yes`
`-yes`	off	Sigue adelante con `-uninstall` o `-migrate` en vez de solo listar lo que haría
`-migrate`	off	Imprime, para cada almacén configurado, lo que una versión anterior dejó allí con una forma que esta ya no escribe y lo que haría falta para ponerlo al día, y sale; sin `-yes` no cambia nada, y con él aplica cada cambio pendiente y vuelve a leer lo que despejó
`-migrate-others`	off	Con `-migrate -yes`, aplica también un cambio a un almacén que guarda filas de cuentas que esta configuración no recoge, o cuyas filas no se pudieron comparar con ella; sin `-migrate` se rechaza con 2
`-card`	ninguno	Hace una pasada y escribe un SVG de resumen en esta ruta; esa pasada recoge todas las familias, digan lo que digan las cadencias
`-card-only`	apagada	Con `-card`, escribe el SVG y nada más: no hace falta ningún destino, no se escribe en ninguno y el fichero de estado se queda como estaba
`-card-theme`	`auto`	`dark`, `light`, `auto` o `both`: la tarjeta clara en `-card` y la oscura a su lado con `_dark` antes de la extensión, en una sola pasada
`-card-motion`	`once`	`once`, `loop` u `off`; `loop` solo cambia `terminal` y `ticker`
`-card-layout`	`summary`	Cuál de los trece diseños dibujar
`-card-fields`	ninguno	Campos que muestra la tarjeta, separados por comas, de entre los campos; vacío significa el valor por omisión del diseño
`-card-width`	el del diseño	Ancho de la tarjeta en píxeles. Cada diseño dibuja entre dos extremos propios, que dicen tanto su sección como `-card-layouts`; `badge-row` la ignora, porque su ancho lo deciden sus píldoras
`-card-speed`	`0.5`	A qué velocidad se reproduce un diseño animado, como decimal de 0 a 1. `0` es la animación más lenta y `1` la más rápida; `0.5` es el ritmo con el que siempre se han dibujado las tarjetas. `0` no es una tarjeta quieta, eso es `-card-motion off`
`-card-layouts`	apagada	Imprime los diseños con los campos y los anchos que dibuja cada uno, y sale

Las cinco que imprimen y salen

-version, -groups, -card-layouts, -list y -backfill-status responden y paran. Las tres primeras no necesitan token ni configuración; -list lee la configuración y le pregunta a GitHub en qué repositorios se resuelven los objetivos, que es la forma barata de comprobar un cambio antes de gastar cuota en una pasada. -backfill-status lee la configuración para encontrar el punto de control del relleno e imprime hasta dónde ha llegado ese recorrido, y después la relectura de una migración cuando hay una en curso; no le pregunta nada a GitHub, así que no necesita token.

ghchronicle -version
ghchronicle -groups
ghchronicle -card-layouts
ghchronicle -config config.yaml -list
ghchronicle -config config.yaml -backfill-status

Lo que una actualización dejó en los almacenes

ghchronicle -config config.yaml -migrate

-migrate contrasta cada almacén configurado con la lista de cambios que lleva el binario, cada uno una medida que una versión anterior escribió con una clave que esta ya no usa, e imprime un bloque por almacén: lo que cada cambio encuentra allí, la prueba, lo que haría falta para ponerlo al día y lo que se volvería a leer de GitHub. No cambia nada. A los almacenes se les hacen preguntas, a GitHub solo se le pide la lista de repositorios, y el fichero de estado se lee y nunca se escribe, así que sale con 0 encuentre lo que encuentre. Sin token funciona igual y dice lo que no pudo comparar. Migraciones explica cómo se decide cada almacén y qué significa cada línea. Cuando hay algo pendiente, el plan termina con la orden que lo aplica y con lo que hace un arranque con el ajuste migrate.

Esa orden, y cualquier otra que ghchronicle imprime para que la ejecutes después (la línea de reanudar de -backfill-status, los avisos de un arranque, la última línea de -setup), nombra la configuración tal como se le dio, entre comillas cuando un shell leería parte de la ruta: comillas simples en Linux y macOS, y dobles en Windows, la única forma que PowerShell y cmd leen como un solo argumento.

ghchronicle -config config.yaml -migrate -yes

Con -yes imprime el mismo plan y después aplica cada cambio pendiente, también los marcados como necesitados de la palabra de alguien, vuelve a leer de GitHub lo que despejó, y dice bajo el plan qué pasó con cada uno. Volver a leerlo es un relleno histórico de las familias que escriben lo despejado, escribiendo solo eso en los almacenes de los que se despejó; -backfill-retry vuelve a por lo que deja, y donde un almacén guardó una copia de las filas antiguas, el informe compara las dos y nombra lo que GitHub ya no sirve. Una relectura cortada guarda un punto de control propio, y la misma orden la retoma, aunque no quede nada por aplicar: volver a leer el historial. Un almacén que guarda filas de cuentas que esta configuración no recoge, o cuyas filas no se pudieron comparar con ella, se deja sin aplicar salvo que se dé también -migrate-others. Necesita un token y la lista de repositorios, y se queda el fichero de estado mientras corre: con el servicio en marcha se niega, nombrando el proceso, y no cambia nada, así que para antes el servicio, y pausa un cron que ejecute -once. Con el destino SQL en la salida estándar, el plan y el informe van a la salida de errores, así que la salida estándar es solo el SQL. Lo que aplica se registra sobre la marcha, así que volver a ejecutarlo tras un fallo sigue sin hacer nada dos veces.

Salida	Cuándo
`0`	`-migrate`, encuentre lo que encuentre; `-migrate -yes` cuando todo lo pendiente se aplicó y se volvió a leer, o no había nada
`1`	`-migrate -yes` dejó algo: un almacén que se negó o no respondió, uno que se dejó sin aplicar, una relectura que no terminó; o se negó a empezar
`2`	Una línea de órdenes que no se puede leer, entre ellas `-migrate-others` sin `-migrate`

Las tres formas de hacer una pasada

ghchronicle -config config.yaml           # el bucle: cada familia en su cadencia
ghchronicle -config config.yaml -once     # una pasada, en primer plano, y salir
ghchronicle -config config.yaml -backfill # el recorrido de la historia, una vez

El bucle es lo que ejecuta un servicio. -once es lo que ejecuta un trabajo programado, y es también la forma más rápida de ver qué hace un cambio de configuración. Un relleno histórico es otra intención y lo dice: recorre cada superficie hasta el final y espera a que se reponga un presupuesto agotado en vez de rendirse.

ghchronicle -config config.yaml -backfill -backfill-since 2y

-families limita un relleno a las familias nombradas, en todos los almacenes configurados: solo algunas familias.

ghchronicle -config config.yaml -backfill -families discussions,outbound

La tarjeta, en una línea

ghchronicle -config config.yaml -card profile.svg -card-only \
  -card-layout github-stats -card-theme dark

-card-only es la combinación que conviene recordar: hace una ejecución que no escribe puntos, así que no necesita ningún destino configurado y se acepta una configuración que de otro modo se rechazaría al arrancar. La tarjeta tiene los diseños y los campos.

-card-width es la única opción que cambia lo que dice una tarjeta y no solo cómo se ve, y en un solo diseño. activity-heatmap se gasta el sitio en datos: dieciséis semanas del calendario de contribuciones en su extremo cercano, veintitrés con el ancho que declara y el año entero que guarda el recolector en su extremo lejano, que cae justo donde cae el año para que a la tarjeta nunca se le pida llenar un sitio para el que no tiene nada. Cualquier otro diseño reparte el mismo contenido por el ancho que le den, así que ensanchar uno de esos compra proporciones y no información, y su extremo lejano es solo una defensa contra una errata. Un ancho fuera de los dos extremos de un diseño se rechaza antes de la pasada, nombrándolos, y -card-layouts los imprime para cada diseño.

ghchronicle -config config.yaml -card calendar.svg -card-only \
  -card-layout activity-heatmap -card-width 700

La velocidad, y lo que no es su extremo lento

-card-speed es un solo número para toda la tarjeta. Todos los diseños animados se escalan juntos, los movimientos continuos con el resto: con el mismo ajuste, la banda del ticker tarda más en dar la vuelta y el cursor del terminal parpadea más despacio. Es un mando y no uno por diseño porque el movimiento que tiene la tarjeta se calibró contra sí mismo, el ciclo de un diseño elegido al lado del de otro, y a quien le parezca lenta la banda le parecerá lento también el tecleo.

0.5 es el centro del rango y es exactamente la tarjeta que este renderizador ha dibujado siempre, byte a byte, así que omitir la opción y pedir 0.5 son la misma orden, y cada extremo llega a la misma distancia de ella: 0 dibuja la animación el doble de larga que la de por omisión, 1 la mitad de larga que la de por omisión.

ghchronicle -config config.yaml -card slow.svg -card-only \
  -card-layout ticker -card-motion loop -card-speed 0.25

Dónde está lo demás

Todo lo que no está en esa tabla es una clave de configuración y no una opción: el fichero es el mapa de todas ellas.

Escrito y mantenido por José Manuel Requena Plens

Licencia MITHistorial de versiones