macOS gcp requirement not clearly documented #27

New Issue

2025-11-15T03:44:25Z

snegov commented

2025-11-15 03:44:25 +00:00

macOS gcp requirement not clearly documented

Priority: Low
Component: README.md, cli.py
Type: Documentation

Description

The code requires gcp (GNU cp) on macOS for the --external-hardlink option, but the README doesn't clearly explain this requirement or how to install it.

Current State

README says "Optional: rsync and GNU cp"
Error message: "gcp should be installed to use --external-hardlink option"
No installation instructions

Users are left to figure out:

What is gcp?
Why isn't the built-in cp sufficient?
How do I install it?

Location

curateipsum/cli.py:77-81

Proposed Solution

1. Improve error message:

if args.external_hardlink and not shutil.which(cp_program):
    if sys.platform == "darwin":
        _lg.error(
            "GNU coreutils required for --external-hardlink on macOS.\n"
            "Install with: brew install coreutils"
        )
    else:
        _lg.error("cp command not found, cannot use --external-hardlink.")
    return 1

2. Update README:

### macOS-Specific Requirements

For the `--external-hardlink` option on macOS, you need GNU coreutils:

```bash
brew install coreutils

This provides gcp, which supports the -l flag for hardlinking (macOS's built-in cp doesn't support this).


## Impact
**Low** - Documentation and error message improvement.

# macOS gcp requirement not clearly documented **Priority:** Low **Component:** README.md, cli.py **Type:** Documentation ## Description The code requires `gcp` (GNU cp) on macOS for the `--external-hardlink` option, but the README doesn't clearly explain this requirement or how to install it. ## Current State - README says "Optional: rsync and GNU cp" - Error message: "gcp should be installed to use --external-hardlink option" - No installation instructions Users are left to figure out: - What is `gcp`? - Why isn't the built-in `cp` sufficient? - How do I install it? ## Location `curateipsum/cli.py:77-81` ## Proposed Solution **1. Improve error message:** ```python if args.external_hardlink and not shutil.which(cp_program): if sys.platform == "darwin": _lg.error( "GNU coreutils required for --external-hardlink on macOS.\n" "Install with: brew install coreutils" ) else: _lg.error("cp command not found, cannot use --external-hardlink.") return 1 ``` **2. Update README:** ```markdown ### macOS-Specific Requirements For the `--external-hardlink` option on macOS, you need GNU coreutils: ```bash brew install coreutils ``` This provides `gcp`, which supports the `-l` flag for hardlinking (macOS's built-in `cp` doesn't support this). ``` ## Impact **Low** - Documentation and error message improvement.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: snegov/cura-te-ipsum#27