FileBarge

FileBarge is a small command-line program for transferring files directly between two machines over TCP. It is useful when netcat is too bare-bones, but setting up FTP, SFTP, or rsync would be unnecessary.

It transfers regular-file contents, can traverse directory inputs, and supports optional compression, checksums, and shared-secret encryption. It deliberately does not transfer directory metadata, empty directories, or symbolic links as links. A symbolic link is followed and its target contents are sent as an ordinary file.

Project goals

Keep the command line and protocol small enough to understand easily.
Build a single native executable with no run-time dependencies beyond the operating system and C library.
Transfer safely: verify a completed temporary file before making it visible at its destination.
Support streams and ordinary files without loading their complete contents into memory.
Provide a documented, versioned wire protocol for independent implementations.

Quick start

Build FileBarge with a POSIX shell, make, and Clang:

make build

This builds both .build/filebarge and .build/fileskiff. make test builds both executables and runs the complete test suite. make deploy builds FileSkiff only for Linux targets; other deployment targets contain FileBarge only. The macOS archives include Intel, Apple-Silicon, and universal builds.

On the receiving machine, choose an output directory and start a receiver:

./.build/filebarge receive downloads/

On the sending machine, send a file to the receiver's address:

./.build/filebarge send receiver.example.net report.pdf

FileBarge uses TCP port 8421 by default. The receiver normally exits after a completed session. Add --listen to accept another sender, or --port 0 to let the operating system choose an available port.

Documentation

Usage explains receiving, sending, paths, and every command-line option.
FileSkiff describes the smaller embedded-system companion executable.
Download provides release archive and macOS download instructions.
Feedback explains how to report bugs and request features.
Development is the entry point for contributors.
Protocol specifies the version 1 FileBarge wire protocol.
Tests describes the unit and end-to-end test suites.

Building and testing

make or make build builds .build/filebarge and .build/fileskiff.
make test builds both executables, builds the unit-test executables, and runs every staged test.
make TEST_STAGES='1 3' test runs only the selected test stages.
make clean removes .build and .test.
make deploy runs the tests and builds release archives with Docker. It includes FileSkiff only in Linux archives.

The compiler must be Clang because the source uses Clang-specific nullability annotations and pragmas.

Security

FileBarge is a direct TCP transfer tool. Do not expose a receiver to untrusted senders. --secret enables encrypted transfers using a shared secret, but the secret may be visible in shell history or process listings. Prefer --secret-file for secrets that must not appear on the command line.

Licensing

FileBarge is free software under the GNU Affero General Public License, version 3 or any later version. See LICENSE.