Contributing to trzsz-go

We warmly welcome contributions to the trzsz-go ecosystem! Whether you are squashing a bug, proposing an enhancement, or expanding our test coverage, your effort makes a difference.

This guide outlines the development environment setup, architectural philosophy, and pull request process.

Development Prerequisites

To build and test trzsz-go locally, ensure you have the following installed:

  • Go Toolkit: Version 1.25 or higher is strictly required as we utilize modern Go standard library features.
  • Make: GNU Make is used to orchestrate builds and tests via the provided Makefile.
  • Git: For version control.

Setting up the Environment

  1. Fork the repository on GitHub.

  2. Clone your fork locally: 

    git clone https://github.com/<your-username>/trzsz-go.git
cd trzsz-go

  3. Ensure all dependencies are fetched and validated: 

    go mod tidy

Project Architecture

Understanding the repository layout will help you navigate the codebase efficiently:

  • cmd/: Contains the main packages for the CLI executables. These are extremely thin wrappers that parse CLI arguments and pass them to the core library.
    • cmd/trz/main.go: Entrypoint for remote upload command.
    • cmd/tsz/main.go: Entrypoint for remote download command.
    • cmd/trzsz/main.go: Entrypoint for the local client wrapper.
  • trzsz/: The core library. This is where the magic happens.
    • filter.go: The TrzszFilter logic that intercepts PTY streams.
    • pipeline.go: Highly concurrent data streaming, encoding, and MD5 hashing logic for fast file transfers.
    • comm.go & transfer.go: Handshake protocols and #DATA: / #SUCC: acknowledgment logic.
    • tmuxcc.go: Specialized logic for parsing tmux Control Mode (-CC) escaping.
    • zmodem.go: Legacy lrzsz fallback integration.
  • examples/: Contains the ssh_client.go sample code illustrating how to embed the Go API.

Building the Binaries

You can compile all executables (trz, tsz, trzsz) simultaneously using the Makefile:

make all

The compiled binaries will be output to the local ./bin directory.

To clean up artifacts:

make clean

Testing Philosophy

We maintain strict test coverage to ensure terminal integrity is never broken across varying OS environments. It is crucial that all tests pass before submitting a Pull Request.

Execute the test suite using:

make test

This executes go test -v -count=1 ./trzsz.

Note: The test suite includes simulated terminal buffer reading (buffer_test.go), chunked pipeline encoding checks (pipeline_test.go), and rigorous regex parsing validation for Zmodem and Tmux CC intercepts.

Submitting a Pull Request

  1. Branching: Create a new, descriptively named branch for your feature or bugfix (git checkout -b feature/osc52-improvements).
  2. Coding: Write your code. If you are adding a feature or fixing a parsing bug, you must add a corresponding test case in the *_test.go files.
  3. Testing: Ensure make test passes successfully locally.
  4. Committing: Use clear, concise commit messages.
  5. Pushing: Push your branch to your fork (git push origin feature/osc52-improvements).
  6. Pull Request: Open a Pull Request against the main branch of the upstream repository. Describe the problem you are solving and link to any relevant issues.

Continuous Integration (CI)

We use GitHub Actions (.github/workflows/gotest.yml). Every push and pull request is automatically built and tested across Ubuntu, macOS, and Windows environments. PRs will not be merged if the CI pipeline fails.