# How the `--force` Option Overrides Existing File Checks in you-get

> Discover how the you-get --force option bypasses file checks by overwriting existing content without prompting. Learn about its mechanism in src/you_get/common.py.

- Repository: [Mort Yao/you-get](https://github.com/soimort/you-get)
- Tags: internals
- Published: 2026-03-06

---

**The `--force` (`-f`) flag in you-get bypasses file existence checks by setting the global `force` variable to `True`, which causes `url_save()` in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) to open files in write-binary mode (`'wb'`) instead of append mode, overwriting any existing content without prompting.**

When downloading media with the `you-get` command-line tool, the utility normally protects existing files by skipping downloads or prompting for confirmation. The `--force` option disables these safeguards entirely, allowing seamless automation and re-downloads. This behavior is implemented across the argument parser and the core download routine in the [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) module.

## Argument Parsing and Global Flag

### CLI Definition in common.py

The flag originates in the argument parser defined in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py). The `download_grp` argument group registers the option as a boolean flag:

```python
download_grp.add_argument('-f', '--force', action='store_true', default=False,
                         help='Force overwriting existing files')

```

When a user invokes `you-get -f`, `argparse` stores `True` in the resulting namespace.

### Global Variable Assignment

After `parser.parse_args()` executes, the `script_main` function (around lines 1708–1709) copies this value into the module-wide variable `force`:

```python
global force
force = args.force

```

This global variable acts as the source of truth for all subsequent file operations during the session.

## File Existence Logic in url_save()

### The Conditional Check

The core download logic resides in `url_save()`, also located in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py). The function first checks whether the target file already exists:

```python
if os.path.exists(filepath):
    if not force and (file_size == os.path.getsize(filepath) or
                      skip_existing_file_size_check):
        # ... skip or prompt logic

```

When **force** is `False`, the downloader will:
- Skip the download if the existing file matches the expected size (or if `--skip-existing-file-size-check` is active).
- Prompt the user to overwrite, or automatically rename the file if `auto_rename` is enabled.

When **force** is `True`, the `if not force` condition evaluates to `False`, bypassing the entire skip/prompt block. The downloader proceeds directly to the overwrite path without checking file sizes or user preferences.

### Open Mode Selection

Later in the same function, the write mode is determined by the `force` flag:

```python
if not force:
    open_mode = 'ab'          # append to a partially-downloaded file

else:
    open_mode = 'wb'          # truncate and start fresh

```

With `--force` enabled, the file opens in **write-binary** mode (`'wb'`). This truncates any existing file contents and writes the new data stream from byte zero, effectively replacing the old file regardless of its previous state.

## Practical Usage Examples

Normal operation respects existing files and avoids accidental data loss:

```bash

# Default behavior: skips or asks before overwriting

you-get https://example.com/video.mp4

```

Enabling the override forces immediate replacement:

```bash

# Force overwrite: replaces video.mp4 without confirmation

you-get --force https://example.com/video.mp4

# Short form equivalent

you-get -f https://example.com/video.mp4

```

## Interaction with Other Flags

The `--force` flag takes precedence over `--auto-rename`. When both flags are present, the force logic executes first, opening the file in `'wb'` mode and overwriting the existing target. The auto-rename logic only triggers when `force` is `False` and a naming collision occurs.

## Summary

- **Argument definition**: The `-f/--force` flag is defined in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py) as a `store_true` action with a default of `False`.
- **Global state**: `script_main` assigns the parsed value to the module-level `force` variable (lines 1708–1709).
- **Existence bypass**: In `url_save()`, the `if not force` guard prevents size comparisons and user prompts when enabled.
- **Overwrite mechanism**: The flag switches the file open mode from append (`'ab'`) to write-binary (`'wb'`), truncating existing files.
- **Precedence**: `--force` overrides `--auto-rename` and `--skip-existing-file-size-check`, ensuring unconditional replacement.

## Frequently Asked Questions

### What happens when I use `--force` with `--auto-rename`?

The `--force` flag takes priority. According to the logic in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py), the downloader checks `force` before evaluating `auto_rename`. When `force` is `True`, the file opens in `'wb'` mode immediately, overwriting any existing file with the same name. The auto-rename logic only executes when `force` is `False` and a collision is detected.

### Does `--force` check file sizes before overwriting?

No. When `--force` is enabled, the downloader bypasses the size comparison logic entirely. Normally, `url_save()` compares `file_size` against `os.path.getsize(filepath)` to detect incomplete downloads, but the `if not force` condition prevents this check from executing, forcing a full re-download regardless of existing file size.

### Which source file controls the overwrite behavior?

The overwrite behavior is implemented in [`src/you_get/common.py`](https://github.com/soimort/you-get/blob/main/src/you_get/common.py). This file contains both the CLI argument definition for `-f/--force` and the `url_save()` function that consumes the global `force` variable to determine whether to append to or replace existing files.

### Is there a short form for `--force`?

Yes. The argument parser defines `-f` as the short alias for `--force`. Both `you-get -f <URL>` and `you-get --force <URL>` produce identical behavior, triggering the unconditional overwrite mechanism described in the `url_save()` implementation.