gh-upload-log

A smart tool to upload log files to GitHub as Gists or Repositories


Overview

gh-upload-log is a CLI tool and JavaScript library that intelligently uploads log files to GitHub. It automatically determines the best upload strategy based on file size:

- Small files (≤100MB): Uploaded as GitHub Gists
- Large files (>100MB): Uploaded as GitHub Repositories with automatic splitting into 100MB chunks

Features

- Automatic strategy selection: Chooses between Gist and Repository based on file size
- Smart file splitting: Automatically splits large files into manageable chunks
- Public/Private control: Upload as public or private (default: private)
- Flexible configuration: CLI arguments, environment variables, or .lenv files using Links Notation
- Cross-platform: Works on macOS, Linux, and Windows
- Dual interface: Use as CLI tool or JavaScript library
- Path normalization: Converts file paths into valid GitHub names
- Verbose logging: Built-in verbose mode using log-lazy for efficient lazy evaluation
- Configurable logging: Customize logging behavior with custom log targets (silent mode, custom loggers, etc.)

Prerequisites

- Bun ≥1.0.0
- Git (installed and configured)
- GitHub CLI (gh) installed and authenticated

To authenticate with GitHub CLI:

``bash
gh auth login
`

Installation

$3

`bash
bun install -g gh-upload-log
`

$3

`bash
bun add gh-upload-log
`

Configuration

gh-upload-log supports multiple configuration methods with the following priority (highest to lowest):

1. CLI arguments - Directly passed command-line options
2. Environment variables - System environment variables
3. .lenv file - Local configuration using Links Notation format
4. Defaults - Built-in default values

$3

The tool now supports .lenv configuration files using Links Notation format through lino-arguments.

Create a .lenv file in your project directory:

`
GH_UPLOAD_LOG_PUBLIC: false
GH_UPLOAD_LOG_VERBOSE: true
GH_UPLOAD_LOG_DESCRIPTION: Production logs
`

The configuration priority is:

1. CLI arguments (highest priority)
2. Environment variables
3. .lenv file
4. Default values (lowest priority)

You can also specify a custom configuration file using the --configuration or -c flag:

`bash
gh-upload-log /path/to/file.log --configuration ./custom.lenv
`

$3

Set environment variables for persistent configuration:

`bash
export GH_UPLOAD_LOG_PUBLIC=true
export GH_UPLOAD_LOG_VERBOSE=true
export GH_UPLOAD_LOG_DESCRIPTION="Production logs"
gh-upload-log /var/log/app.log
`

$3

- GH_UPLOAD_LOG_PUBLIC - Make uploads public (default: false)
- GH_UPLOAD_LOG_PRIVATE - Make uploads private (default: true)
- GH_UPLOAD_LOG_AUTO - Enable automatic strategy selection (default: true)
- GH_UPLOAD_LOG_ONLY_GIST - Force gist uploads only (default: false)
- GH_UPLOAD_LOG_ONLY_REPOSITORY - Force repository uploads only (default: false)
- GH_UPLOAD_LOG_DRY_MODE - Enable dry run mode (default: false)
- GH_UPLOAD_LOG_DESCRIPTION - Default description for uploads
- GH_UPLOAD_LOG_VERBOSE - Enable verbose output (default: false)

See .lenv.example for a complete configuration template.

CLI Usage

$3

`bash


Upload a log file (private by default)

gh-upload-log /path/to/logfile.log

Upload as public

gh-upload-log /path/to/logfile.log --public

Upload with description

gh-upload-log /path/to/logfile.log --description "My application logs"
`

$3

`
Usage: gh-upload-log [options]

Options:
--public, -p Make the upload public (default: private)
--private Make the upload private (default)
--auto Automatically choose upload strategy (default: true)
--only-gist Upload only as GitHub Gist (disables auto mode)
--only-repository Upload only as GitHub Repository (disables auto mode)
--dry-mode, --dry Dry run - show what would be done without uploading
--description, -d Description for the upload
--verbose, -v Enable verbose output
--help, -h Show help
--version Show version number
`

$3

`bash


Upload private log file (auto mode)

gh-upload-log /var/log/app.log

Upload public log file (auto mode)

gh-upload-log /var/log/app.log --public

Upload only as gist

gh-upload-log ./error.log --only-gist

Upload only as repository

gh-upload-log ./large.log --only-repository --public

Dry run mode - see what would happen

gh-upload-log ./app.log --dry-mode

Upload with custom description

gh-upload-log ./debug.log -d "Debug logs from production" --public

Disable auto mode and force repository

gh-upload-log ./file.log --no-auto --only-repository
`

Library Usage

$3

`javascript
import { uploadLog } from 'gh-upload-log';

// Upload a log file (private by default)
const result = await uploadLog({
filePath: '/path/to/logfile.log',
});
console.log('Uploaded to:', result.url);

// Upload as public with verbose logging
const publicResult = await uploadLog({
filePath: '/path/to/logfile.log',
isPublic: true,
description: 'My application logs',
verbose: true,
});
console.log('Public URL:', publicResult.url);

// Upload with custom logger (silent mode)
const customLogger = {
log: () => {}, // Silent logging
error: (msg) => console.error('ERROR:', msg),
};

const result = await uploadLog({
filePath: '/path/to/logfile.log',
logger: customLogger,
});
`

$3

#### uploadLog(options)

Main function to upload a log file. Automatically determines the best strategy.

Parameters:

- options (object):
- filePath (string, required): Path to the log file
- isPublic (boolean): Make upload public (default: false)
- auto (boolean): Automatically choose strategy (default: true)
- onlyGist (boolean): Upload only as gist (disables auto mode)
- onlyRepository (boolean): Upload only as repository (disables auto mode)
- dryMode (boolean): Dry run mode - don't actually upload
- description (string): Description for the upload
- verbose (boolean): Enable verbose logging (default: false)
- logger (object): Custom logging target (default: console)

Returns: Promise