How the Auto-Rename Feature Handles Filename Conflicts in you-get

The auto-rename feature in you-get automatically appends incremental numeric suffixes like (1), (2) to filenames when conflicts are detected, ensuring downloads never fail due to existing files.

When downloading videos or other media with you-get, the tool must decide what to do when a target filename already exists. The auto-rename feature provides a hands-free solution that generates unique filenames without user intervention. This article examines the conflict detection logic, the algorithm that constructs new names, and the specific implementation in src/you_get/common.py.

How Filename Conflicts Are Detected

Before any download begins, you-get constructs the full target path (filepath) based on the video title, output directory, and file extension. The program then checks whether a file already exists at that location using standard filesystem operations.

If a conflict is detected, you-get evaluates two command-line flags to determine the next action: --force and --auto-rename (or -a).

Conflict Resolution Logic: Force vs. Auto-Rename vs. Interactive

The behavior follows a strict priority depending on which flags are passed:

• --force is set: The existing file is overwritten immediately (after a confirmation prompt in some versions), regardless of the auto-rename setting.
• --auto-rename is not set: The program pauses and prompts the user interactively to decide whether to overwrite the file.
• --auto-rename is set: The program bypasses user interaction and automatically generates a new filename using the algorithm described below, then retries the existence check.

The Auto-Rename Algorithm in src/you_get/common.py

The core renaming logic resides in src/you_get/common.py between lines 916–928. The implementation uses regular expressions to detect and increment numeric suffixes, ensuring that filenames follow the pattern name (N).ext.

Step 1: Splitting the Filename

The algorithm first deconstructs the existing filepath into its base name and extension:

path, ext = os.path.basename(filepath).rsplit('.', 1)

This separates video.mp4 into path="video" and ext="mp4".

Step 2: Detecting Existing Numeric Suffixes

The code compiles a regex pattern to identify suffixes in the format (N) where N is a positive integer:

finder = re.compile(r' \([1-9]\d*?\)$')

This pattern specifically looks for a space, opening parenthesis, digits (not starting with zero), and closing parenthesis at the end of the base name.

Step 3: Generating the New Filename

If no numeric suffix is found, the algorithm appends (1) before the extension:

thisfile = path + ' (1).' + ext

If a suffix already exists (e.g., video (3).mp4), the code defines a helper function to increment the captured number:

def numreturn(a):
    return ' (' + str(int(a.group()[2:-1]) + 1) + ').'

thisfile = finder.sub(numreturn, path) + ext

This transforms video (3).mp4 into video (4).mp4.

Step 4: Reassembling the Path and Retrying

The new filename is joined back with the original directory, and the existence check loops again:

filepath = os.path.join(os.path.dirname(filepath), thisfile)

The loop continues until a non-conflicting name is found, at which point the download proceeds with the newly generated filepath.

Windows-Specific Safeguard

After a download completes, you-get performs an additional safety check on Windows systems to handle potential lingering conflicts. In src/you_get/common.py at lines 332–336, the code verifies write access to the target file:

if os.access(filepath, os.W_OK):
    # proceed with final rename/move

else:
    # apply final fallback name with " (2)" suffix

If the file is still inaccessible (locked by another process or existing with restricted permissions), the system appends a final fallback suffix " (2)" before calling os.rename, ensuring the operation never fails silently.

Using Auto-Rename from the Command Line

To enable automatic renaming when downloading media, pass the -a or --auto-rename flag:

you-get -a https://www.bilibili.com/video/av123456

If video.mp4 already exists in the output directory, you-get will automatically save the new file as video (1).mp4, then video (2).mp4, and so on, without prompting for user input.

Programmatic Use in Python

When using you-get as a library, you can enable the same behavior by setting the global auto_rename flag before calling download functions:

import you_get.common as yg

# Enable automatic conflict resolution

yg.auto_rename = True

# Proceed with download

yg.download_urls(
    urls=['https://example.com/video.mp4'],
    title='video',
    ext='mp4',
    output_dir='.',
    merge=False,
    force=False,
)

The download_urls function will internally invoke the renaming logic in src/you_get/common.py whenever it detects an existing file, ensuring the download completes without manual intervention.

Summary

• Conflict Detection: you-get checks for existing files before starting downloads and reacts to the --force and --auto-rename flags.
• Auto-Rename Logic: Located in src/you_get/common.py (lines 916–928), the feature uses regex pattern r' \([1-9]\d*?\)$' to detect and increment numeric suffixes like (1), (2).
• Algorithm Steps: Splits filename into base and extension, detects existing numeric suffixes, increments or appends (1), and loops until a unique name is found.
• Windows Safeguard: Additional check at lines 332–336 ensures write access before final rename, with fallback to (2) suffix if needed.
• Usage: Enable via -a/--auto-rename CLI flag or set yg.auto_rename = True when using as a library.

Frequently Asked Questions

What happens if both --force and --auto-rename are used together?

When both flags are provided, --force takes precedence. According to the logic in src/you_get/common.py, the program will overwrite the existing file rather than generating a new name. The auto-rename logic is only triggered when --force is not set and a conflict is detected.

Does auto-rename work on all operating systems?

Yes, the auto-rename implementation in src/you_get/common.py uses standard Python os.path functions and regular expressions that are platform-independent. However, Windows users benefit from an additional safeguard (lines 332–336) that checks file write permissions before the final rename operation, which handles Windows-specific file locking scenarios.

Can I customize the numeric suffix format used by auto-rename?

No, the suffix format is hardcoded in the regex pattern r' \([1-9]\d*?\)$' and the string concatenation logic within src/you_get/common.py. The format strictly follows the pattern (N) (space, parenthesis, number, parenthesis) before the file extension. To use a different format, you would need to modify the source code in the numreturn function and the regex compilation line.

Is there a limit to how many times auto-rename will increment?

There is no explicit upper bound coded in the rename loop at lines 916–928. The while loop continues indefinitely until os.path.exists(filepath) returns False, meaning it will keep incrementing the numeric suffix (e.g., from (999) to (1000)) until a unique filename is found. In practice, filesystem limits or path length restrictions would be reached long before any coded limit.

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