Configuración

Configura GitScrum CLI con config global y .gitscrum.yml a nivel de proyecto. Variables de entorno, ajustes de timer y formato de ramas.

El CLI de GitScrum usa un sistema de configuración por capas: global, proyecto y variables de entorno.

Jerarquía de Configuración

La prioridad (de mayor a menor):

Variables de Entorno — GITSCRUM_*
Configuración de Proyecto — .gitscrum.yml en el directorio actual
Configuración Global — ~/.gitscrum/config.yml
Valores Predeterminados — Integrados en el CLI

Configuración Global

Ubicación: ~/.gitscrum/config.yml

Usando Comandos

# Establecer valor
gitscrum config set default_project mi-proyecto
gitscrum config set timer.auto_start true

# Obtener valor
gitscrum config get default_project

# Listar toda la configuración
gitscrum config list

# Eliminar valor
gitscrum config unset timer.auto_start

Archivo de Configuración

# ~/.gitscrum/config.yml

# Proyecto predeterminado
default_project: mi-proyecto

# Formato de salida (text, json, yaml)
output_format: text

# Timer
timer:
  auto_start: false
  idle_timeout: 15m
  remind_interval: 30m

# Git
git:
  branch_format: "{type}/{id}-{slug}"
  default_type: feature

# Editor para ediciones (standup, comentarios)
editor: code

# Aliases
aliases:
  dash: acme-dashboard
  api: api-v2

Configuración de Proyecto

Crea .gitscrum.yml en la raíz de tu repositorio.

Estructura Básica

# .gitscrum.yml

# Requerido: vincula el directorio al proyecto de GitScrum
project: mi-proyecto

Configuración Completa

# .gitscrum.yml

project: mi-proyecto

# Configuración del Timer
timer:
  auto_start: true          # Iniciar timer al hacer checkout de rama con tarea
  auto_stop: true           # Pausar timer en inactividad
  idle_timeout: 15m         # Umbral de inactividad
  remind_interval: 30m      # Recordatorio de timer corriendo
  round_to: 5m              # Redondear tiempos registrados
  minimum_entry: 5m         # Tiempo mínimo para registrar
  require_note: false       # Requerir nota al parar

# Integración Git
git:
  branch_format: "{type}/{id}-{slug}"
  default_type: feature
  max_slug_length: 50
  remote: origin            # Remote para detección de repo

# Git Hooks
hooks:
  commit_msg:
    enabled: true
    format: "[{id}] "
    skip_if_present: true
  post_checkout:
    enabled: true
    switch_timer: true
    show_task: true

# Standup
standup:
  reminder:
    enabled: true
    time: "09:00"
    days: ["monday", "tuesday", "wednesday", "thursday", "friday"]

# CI/CD
ci:
  update_on_deploy: true
  deploy_status: deployed

Variables de Entorno

Sobrescriben cualquier configuración de archivo.

Variable	Descripción
`GITSCRUMACCESSTOKEN`	Token OAuth (para CI/CD)
`GITSCRUM_PROJECT`	Sobrescribir proyecto detectado
`GITSCRUM_BRANCH`	Sobrescribir rama detectada
`GITSCRUMTASKID`	Sobrescribir ID de tarea detectado
`GITSCRUMAPIURL`	Endpoint API personalizado
`GITSCRUM_DEBUG`	Habilitar salida de debug (1 o true)
`GITSCRUMHOOKSDISABLED`	Deshabilitar git hooks (1 o true)
`GITSCRUMNOCOLOR`	Deshabilitar salida coloreada

Ejemplos de Uso

# CI/CD - autenticación via variable de entorno
export GITSCRUM_ACCESS_TOKEN="tu-token-oauth"
gitscrum task list

# Desarrollo - sobrescribir proyecto temporalmente
GITSCRUM_PROJECT="otro-proyecto" gitscrum task list

# Debugging
GITSCRUM_DEBUG=1 gitscrum timer start

Referencia de Configuraciones

Timer

Clave	Tipo	Predeterminado	Descripción
`timer.auto_start`	bool	`false`	Iniciar timer al cambiar de rama
`timer.auto_stop`	bool	`true`	Pausar en inactividad
`timer.idle_timeout`	duration	`15m`	Tiempo de inactividad
`timer.remind_interval`	duration	`30m`	Intervalo de recordatorios
`timer.round_to`	duration	`1m`	Redondeo de tiempo
`timer.minimum_entry`	duration	`1m`	Entrada mínima
`timer.require_note`	bool	`false`	Nota obligatoria

Git

Clave	Tipo	Predeterminado	Descripción
`git.branch_format`	string	`{type}/{id}-{slug}`	Formato de rama
`git.default_type`	string	`feature`	Tipo predeterminado
`git.maxsluglength`	int	`50`	Máximo largo del slug
`git.remote`	string	`origin`	Remote para detección

Formato de Rama

Placeholders disponibles:

Placeholder	Valor
`{id}`	ID de tarea (ej., `GS-123`)
`{type}`	Tipo de tarea (feature, bug, chore)
`{slug}`	Título slugificado
`{user}`	Tu username

Ejemplos:

# Salida: feature/GS-123-implementar-oauth
git:
  branch_format: "{type}/{id}-{slug}"

# Salida: john/GS-123
git:
  branch_format: "{user}/{id}"

# Salida: GS-123-implementar-oauth
git:
  branch_format: "{id}-{slug}"

Soporte para Monorepo

Para monorepos con múltiples proyectos:

repo/
├── packages/
│   ├── api/
│   │   └── .gitscrum.yml  # project: api-backend
│   └── web/
│       └── .gitscrum.yml  # project: web-frontend
└── .gitscrum.yml          # project: monorepo (raíz)

El CLI usa el .gitscrum.yml más cercano:

$ cd packages/api
$ gitscrum task list
# Lista tareas del proyecto api-backend

$ cd ../..
$ gitscrum task list
# Lista tareas del proyecto monorepo

Validación de Configuración

Verifica si tu configuración es válida:

gitscrum config validate

✓ Configuración global: ~/.gitscrum/config.yml
✓ Configuración de proyecto: .gitscrum.yml
✓ Proyecto 'mi-proyecto' accesible
✓ Autenticación válida

Configuración efectiva:
  project: mi-proyecto
  timer.auto_start: true
  timer.idle_timeout: 15m

Perfiles de Configuración

Cambia entre configuraciones (útil para múltiples cuentas):

# Crear perfil
gitscrum config profile create trabajo

# Cambiar de perfil
gitscrum config profile use trabajo

# Listar perfiles
gitscrum config profile list