dotnet-gitmoji: un CLI de gitmoji para el mundo dotnet

Descripción del proyecto

dotnet-gitmoji es una pequeña herramienta de .NET 10 que lleva la convención de commits de gitmoji a un flujo .NET. Puedes instalarla globalmente para uso personal o fijarla en el tool manifest local de un repositorio para uso en equipo. Desde ahí tienes dos caminos de adopción: un hook prepare-commit-msg administrado a través de Husky.Net, o dotnet-gitmoji commit como reemplazo interactivo del comando nativo de Git. En cualquiera de los dos caminos, la herramienta te pide un gitmoji, te permite hacer fuzzy search sobre la lista completa y formatea el mensaje de commit final.

La forma que más me interesa es el flujo de equipo. Cuando un repositorio deja versionados .config/dotnet-tools.json, .husky/ y Directory.Build.targets, un integrante puede clonarlo, ejecutar dotnet restore o abrir la solución en Visual Studio o Rider, y obtener el mismo prompt de gitmoji en el siguiente commit. Así toda la convención se queda dentro de NuGet, MSBuild y el SDK de .NET en lugar de depender de Node.js sólo para compartir un hook de commit.

Tecnologías utilizadas

Arquitectura

La herramienta sigue la estructura estándar de CliFx. Program.cs configura el contenedor de DI, CliFx resuelve el comando pedido desde el service provider, y el comando delega el trabajo real a un servicio. Los servicios son interface-first, y eso es lo que hace que los tests con xUnit y NSubstitute sean fáciles de escribir. Al mismo flujo de commit se accede desde dos puntos de entrada: el hook prepare-commit-msg de Git y el comando interactivo commit.

flowchart LR
    subgraph CLI["CliFx commands"]
        MAIN["Program.cs\nDI setup + app entry"]
        CLIENT_CMDS["commit\nlist · search\nconfig · update"]
        HOOK_CMDS["hook\ninit · remove"]
    end

    subgraph CORE["Shared core"]
        GIT["GitService\nhook detect/install\nstage changes"]
        PROMPT["PromptService\nfuzzy selector UI"]
        FUZZY["GitmojiFuzzyMatcher\nscoring & ranking"]
        CONFIG["ConfigurationService\n.gitmojirc.json → global"]
        VALIDATOR["CommitMessageValidator\nparse existing message"]
    end

    subgraph DATA["Data & presentation"]
        PROVIDER["GitmojiProvider\nAPI → cache → embedded"]
        MODELS["Gitmoji · ToolConfiguration\nEmojiFormat · ValidationResult"]
    end

    MAIN --> CLIENT_CMDS
    MAIN --> HOOK_CMDS

    CLIENT_CMDS --> PROMPT
    CLIENT_CMDS --> PROVIDER
    CLIENT_CMDS --> CONFIG

    HOOK_CMDS --> GIT
    HOOK_CMDS --> PROMPT
    HOOK_CMDS --> PROVIDER
    HOOK_CMDS --> VALIDATOR

    PROMPT --> FUZZY
    FUZZY --> MODELS
    PROVIDER --> MODELS
    CONFIG --> MODELS

El diagrama de arquitectura muestra de qué se encarga cada capa. El diagrama de secuencia de abajo muestra qué se ejecuta realmente al hacer un commit. Ambos puntos de entrada convergen en PromptService, que controla el selector difuso (fuzzy) y luego delega en CommitMessageService la escritura del resultado. La única diferencia está en quién invoca git commit al final: en modo hook, Git ya tiene el control, así que la herramienta simplemente reescribe el archivo del mensaje; en modo cliente, GitService invoca Git directamente.

flowchart LR
    A[git commit] --> B[prepare-commit-msg]
    B --> C[dotnet-gitmoji hook]
    C --> D[PromptService]
    D --> E[GitmojiProvider<br/>cache or embedded default]
    D --> F[CommitMessageService]
    F --> G[.git/COMMIT_EDITMSG]

    H[dotnet-gitmoji commit] --> D
    F --> I[GitService<br/>CliWrap -> git]

Características clave

Modo hook. dotnet-gitmoji init --mode shell instala un hook prepare-commit-msg administrado por Husky.Net que intercepta cada git commit. init --mode task-runner apunta a repositorios que ya usan el task runner de Husky.Net, y el hook se salta merge commits, squash merges, amends e interactive rebases para no interrumpir los flujos automatizados.

Modo cliente. dotnet-gitmoji commit actúa como reemplazo directo de git commit, y también admite --title, --scope y --message cuando quieres saltarte parte del prompt. Se desactiva cuando el hook ya está instalado, para que el emoji nunca se aplique dos veces.

Puesta en marcha del equipo. La ruta compartida vive en .config/dotnet-tools.json, .husky/ y Directory.Build.targets. En repositorios con archivo de proyecto, normalmente basta con dotnet restore o con abrir el IDE para restaurar las herramientas y volver a establecer core.hooksPath a través de Husky.Net.

Fuzzy search y descubrimiento. dotnet-gitmoji search <keyword> y el picker en vivo comparten el mismo fuzzy matcher, que busca por nombre, shortcode y descripción del emoji. dotnet-gitmoji list es la forma no interactiva de inspeccionar el catálogo completo.

Opciones de configuración. El asistente interactivo config y el .gitmojirc.json a nivel repositorio exponen los mismos controles: salida en emoji o shortcode, prompts opcionales de scope y mensaje, capitalización del título, sugerencias de scope personalizadas, auto-stage, commits firmados y una URL personalizada para el feed de gitmojis.

Cadena de resolución de configuración. La herramienta lee primero .gitmojirc.json desde la raíz del repo (subiendo por los directorios padre), después ~/.dotnet-gitmoji/config.json, y al final los defaults incluidos. Los ajustes de equipo viajan con el repo, y las preferencias personales se quedan en el home.

Comandos operativos. update refresca la lista cacheada de gitmojis, y remove se encarga del desmontaje del hook. Para hooks administrados por Husky.Net, remove imprime los pasos de limpieza en lugar de editar .husky/ silenciosamente.

Paridad entre instalación local y global. La herramienta detecta si fue instalada de forma global o por proyecto, y escribe la invocación correcta (dotnet-gitmoji o dotnet tool run dotnet-gitmoji) dentro del script de hook generado.

Retos técnicos

public static async Task<int> Main(string[] args)
{
    TtyConsoleInput.TryReopenStdin();
    // DI container and CliFx application follow
}

// GitService.cs — detects local vs. global tool manifest at hook-generation time
private async Task<bool> IsLocalToolManifestAsync()
{
    var repoRoot = await GetRepositoryRootAsync();
    var manifestPath = Path.Combine(repoRoot, ".config", "dotnet-tools.json");

    if (!File.Exists(manifestPath))
        return false;

    var json = await File.ReadAllTextAsync(manifestPath);
    var node = JsonNode.Parse(json);
    var tools = node?["tools"] as JsonObject;
    return tools?.ContainsKey("dotnet-gitmoji") ?? false;
}

private async Task<string> BuildShellHookCommandAsync()
{
    var isLocal = await IsLocalToolManifestAsync();
    var invocation = isLocal ? "dotnet tool run dotnet-gitmoji" : "dotnet-gitmoji";
    return $"{invocation} \"$1\" \"$2\"";
}

// CommitCommand.cs — guard at the top of ExecuteAsync
public async ValueTask ExecuteAsync(IConsole console)
{
    if (await _gitService.IsHookInstalledAsync())
    {
        await console.Error.WriteLineAsync(
            "Error: The prepare-commit-msg hook is already configured to use dotnet-gitmoji.\n" +
            "Using both hook mode and client mode would apply the emoji twice.\n\n" +
            "Either:\n" +
            "  • Use 'git commit' and let the hook handle it (hook mode)\n" +
            "  • Remove the hook from .husky/prepare-commit-msg and use 'dotnet-gitmoji commit' (client mode)");
        throw new CommandException("Cannot use client mode while hook is installed.", 1);
    }

    // ... rest of commit flow
}

Lo que este proyecto demuestra

Resultados

El resultado es simple: un equipo de .NET puede adoptar la convención de gitmoji sin salir de NuGet y MSBuild, y la misma herramienta sigue funcionando como un CLI personal más liviano cuando un hook a nivel repositorio sería demasiado.

Enlaces

• Repositorio: dotnet-gitmoji ➡️
• Paquete en NuGet: dotnet-gitmoji ➡️
• Convención de gitmoji: gitmoji.dev ➡️
• Husky.Net: Husky.Net ➡️

Foto por Tim Witzdam ➡️ en Unsplash ➡️