How Croc Handles File Renaming to Avoid Overwrite Prompts

Croc eliminates interactive overwrite prompts by offering a --rename flag that automatically appends incrementing numbers (e.g., " (1)", " (2)") to incoming filenames when hash mismatches are detected, allowing transfers to proceed without user intervention.

When transferring files with the schollz/croc command-line tool, collisions between incoming and existing files typically trigger interactive prompts asking whether to overwrite or resume. According to the croc source code, the --rename flag provides a deterministic mechanism that handles these conflicts automatically by generating unique filenames on the receiver side.

The --rename Flag Mechanism

The automatic renaming system operates through a four-stage pipeline that detects conflicts, verifies content differences, and generates non-conflicting filenames without interrupting the transfer workflow.

Step 1: CLI Flag Detection

In src/cli/cli.go, the application defines the --rename option as a boolean flag (lines 141-142). When the receiver enables this flag, it sets c.Options.Rename to true for the transfer session. This configuration signals the underlying transfer logic to bypass the standard overwrite confirmation prompts and instead activate the automatic renaming code path.

Step 2: Hash Mismatch Detection

During file reception in src/croc/croc.go (lines 2626-2632), croc compares the cryptographic hash of the existing local file against the hash supplied by the sender. If the hashes differ—indicating the files contain different content—and the --rename flag is active, the execution flow enters the rename handling block rather than triggering the interactive overwrite or resume logic.

Step 3: Generating Unique Filenames

The renaming implementation relies on utils.UnusedFilename(folder, name) located in src/utils/utils.go (lines 83-97). This utility function checks whether the requested filename already exists in the target directory. If a collision exists, the function appends " (1)", " (2)", etc., immediately before the file extension, iterating until it identifies a filename that does not exist on the local filesystem.

Step 4: Continuing the Transfer

Once UnusedFilename() returns a unique name, croc prints a notification to the terminal (e.g., Receiving 'example.txt' as 'example (1).txt') and proceeds with the transfer using the newly generated filename (lines 2629-2631 in src/croc/croc.go). The entire process occurs without requiring user confirmation.

Usage Examples

Receiving Files with Automatic Renaming

To enable automatic renaming when receiving files:

croc --receive --rename

If example.txt already exists locally, croc will store the incoming file as example (1).txt.

Sender Configuration

The sender does not require any special flags. The automatic renaming behavior is governed entirely by the receiver's configuration:

# Sender runs standard command

croc send secretfile.txt

Forcing Overwrites Instead

If you prefer to overwrite existing files without prompts or renaming, use the --overwrite flag:

croc --receive --overwrite

Summary

• The --rename flag in croc automatically renames incoming files when hash mismatches are detected, eliminating interactive overwrite prompts.
• Hash comparison logic in src/croc/croc.go (lines 2626-2632) determines whether incoming files differ from existing local copies before triggering a rename.
• The utils.UnusedFilename() function in src/utils/utils.go (lines 83-97) generates unique filenames by appending incrementing numbers in parentheses before file extensions.
• This behavior is controlled entirely by the receiver; senders use standard commands without additional flags.

Frequently Asked Questions

How do I enable automatic file renaming in croc?

Enable the --rename flag when receiving files: croc --receive --rename. When enabled, croc automatically renames any incoming file that conflicts with an existing local file, appending " (1)", " (2)", etc., before the extension to avoid overwrites.

Where does croc implement the automatic renaming logic?

The implementation spans three key files: src/cli/cli.go defines the CLI flag (lines 141-142), src/croc/croc.go contains the hash comparison and rename decision logic (lines 2626-2632), and src/utils/utils.go provides the UnusedFilename helper function (lines 83-97) that generates unique filenames.

Does the sender need to use the --rename flag?

No. The automatic renaming behavior is controlled entirely by the receiver. The sender executes the standard croc send command without additional flags, while the receiver determines whether to enable automatic renaming with --rename or force overwrites with --overwrite.

What naming convention does croc use for renamed files?

Croc appends an incrementing number in parentheses immediately before the file extension. For example, if document.pdf exists locally, incoming files are renamed to document (1).pdf, document (2).pdf, and so forth until a unique filename is found.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}