# How Croc Handles File Renaming to Avoid Overwrite Prompts

> Learn how Croc uses the --rename flag to automatically rename files and prevent overwrite prompts during transfers for a seamless experience.

- Repository: [Zack/croc](https://github.com/schollz/croc)
- Tags: internals
- Published: 2026-07-26

---

**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](https://github.com/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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:

```bash
croc --receive --rename

```

If [`example.txt`](https://github.com/schollz/croc/blob/main/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:

```bash

# 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:

```bash
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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/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`](https://github.com/schollz/croc/blob/main/src/cli/cli.go) defines the CLI flag (lines 141-142), [`src/croc/croc.go`](https://github.com/schollz/croc/blob/main/src/croc/croc.go) contains the hash comparison and rename decision logic (lines 2626-2632), and [`src/utils/utils.go`](https://github.com/schollz/croc/blob/main/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.