tlnw-get-file

tlnw-get-file is a small cross-platform Python CLI that retrieves a single file or folder from a Git repository by using sparse checkout and then moves it into a relative destination under the current working directory.

Installation

python -m pip install .

Usage

tlnw-get-file --git --repo https://github.com/owner/repo.git --source path/to/file.txt --dest output.txt

The CLI always supports these common options:

• --help: show the current version, usage, and available options
• --debug: enable debug logging
• --version: print the current version

Version 0.2.0 requires --git mode.

Git mode

• --repo must be an HTTPS repository URL.
• --source must be a single relative file or folder path inside the repository.
• --dest must be a relative path from the current working directory and must not contain .. path segments.
• --merge is optional and accepts replace or discard when the resolved final destination path already exists.

If TLNW_GIT_ACCESS_TOKEN is set, the command injects it into the HTTPS clone URL by using x-access-token authentication. If the variable is absent, the repository is cloned as a public repository.

Destination behavior

• If --dest points to an existing directory, the retrieved source is moved inside it.
• If --dest ends with / or \, that directory is created and the retrieved source is moved inside it.
• Otherwise, a file source is written to the exact destination file path.
• Otherwise, a directory source is moved to the exact destination directory path, which allows renaming the retrieved folder.
• --merge is evaluated only after the final destination path is resolved. If the resolved path does not exist, the move proceeds normally and any --merge value is ignored.
• If the resolved final destination path already exists and --merge is omitted, the command fails.
• --merge replace recursively applies the source onto the destination, overwriting conflicting files or folders while keeping destination-only entries.
• --merge discard recursively applies only source paths that do not already exist, preserving conflicting destination files or folders.

Examples

Retrieve a file to a specific output filename:

tlnw-get-file --git --repo https://github.com/owner/repo.git --source docs/spec.md --dest specs/current.md

Retrieve a folder into a destination directory:

tlnw-get-file --git --repo https://github.com/owner/repo.git --source templates/api --dest vendor/

Recursively overwrite conflicting paths while keeping destination-only files:

tlnw-get-file --git --repo https://github.com/owner/repo.git --source templates/api --dest vendor/ --merge replace

Recursively keep conflicting destination paths and import only new source paths:

tlnw-get-file --git --repo https://github.com/owner/repo.git --source templates/api --dest vendor/ --merge discard

Enable debug logging:

tlnw-get-file --debug --git --repo https://github.com/owner/repo.git --source path/to/file.txt --dest output.txt

Development

python -m pip install -e .[dev]
python -m pytest