# Long-running process protocol

2025-08-28

This protocol is used when Git needs to communicate with an external process throughout the entire life of a single Git command. All communication is in pkt-line format (see gitprotocol-common(5)) over standard input and standard output.

## Handshake

Git starts by sending a welcome message (for example, "git-filter-client"), a list of supported protocol version numbers, and a flush packet. Git expects to read the welcome message with "server" instead of "client" (for example, "git-filter-server"), exactly one protocol version number from the previously sent list, and a flush packet. All further communication will be based on the selected version. The remaining protocol description below documents "version=2". Please note that "version=42" in the example below does not exist and is only there to illustrate how the protocol would look like with more than one version.

After the version negotiation Git sends a list of all capabilities that it supports and a flush packet. Git expects to read a list of desired capabilities, which must be a subset of the supported capabilities list, and a flush packet as response:

    packet:          git> git-filter-client
    packet:          git> version=2
    packet:          git> version=42
    packet:          git> 0000
    packet:          git< git-filter-server
    packet:          git< version=2
    packet:          git< 0000
    packet:          git> capability=clean
    packet:          git> capability=smudge
    packet:          git> capability=not-yet-invented
    packet:          git> 0000
    packet:          git< capability=clean
    packet:          git< capability=smudge
    packet:          git< 0000

## Shutdown

Git will close the command pipe on exit. The filter is expected to detect EOF and exit gracefully on its own. Git will wait until the filter process has stopped.