Metadata-Version: 2.4
Name: tlnw-get-file
Version: 0.2.0
Summary: Retrieve a single file or folder from a Git repository using sparse checkout.
Author: Tellers Network
Keywords: git,cli,sparse-checkout,files
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# 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

```bash
python -m pip install .
```

## Usage

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Enable debug logging:

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

## Development

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