Skip to content

Command-Line Options

text
f2 v2.0.0
Ayooluwa Isaiah <ayo@freshman.tech>

f2 bulk renames files and directories, matching files against a specified
pattern. It employs safety checks to prevent accidental overwrites and
offers several options for fine-grained control over the renaming process.

Project repository: https://github.com/ayoisaiah/f2

USAGE
  f2 FLAGS [OPTIONS] [PATHS TO FILES AND DIRECTORIES...]
  command | f2 FLAGS [OPTIONS]

POSITIONAL ARGUMENTS
  [PATHS TO FILES AND DIRECTORIES...]
    Optionally provide one or more files and directories to search for matches.
    If omitted, it searches the current directory alone. Also, note that
    directories are not searched recursively unless --recursive/-R is used.

FLAGS
  --csv
    Load a CSV file, and rename according to its contents.

  -f, --find
    A regular expression pattern used for matching files and directories.
    It accepts the syntax defined by the RE2 standard and defaults to .*
    if omitted which matches the entire file/directory name.

    When -s/--string-mode is used, this pattern is treated as a literal string.

  -r, --replace
    The replacement string which replaces each match in the file name.
    It supports capture variables, built-in variables, and exiftool variables.
    If omitted, it defaults to an empty string.

  -u, --undo
    Undo the last renaming operation performed in the current working directory.

OPTIONS
  --allow-overwrites
    Allows the renaming operation to overwrite existing files.
    Caution: Using this option can lead to unrecoverable data loss.

  -c, --clean
    Clean empty directories that were traversed in a renaming operation.

  -E, --exclude
    Excludes files and directories that match the provided regular expression.
    This flag can be repeated to specify multiple exclude patterns.

    Example:
      -E 'json' -E 'yml' (filters out JSON and YAML files)
      -E 'json|yaml' (equivalent to the above)

    Note:
      This does not prevent recursing into matching directories (use
      --exclude-dir instead).

  --exclude-dir
    Prevents F2 from recursing into directories that match the provided regular
    expression pattern.

  --exiftool-opts
    Provides options to customize Exiftool's output when using ExifTool
    variables in replacement patterns.

    Supported options:
      --api
      --charset
      --coordFormat
      --dateFormat
      --extractEmbedded

    Example:
      $ f2 -r '{xt.GPSDateTime}' --exiftool-opts '--dateFormat %Y-%m-%d'

  -x, --exec
    Executes the renaming operation and applies the changes to the filesystem.

  -F, --fix-conflicts
    Automatically fixes renaming conflicts using predefined rules.

  --fix-conflicts-pattern
    Specifies a custom pattern for renaming files when conflicts occur.
    The pattern should be a valid Go format string containing a single '%d'
    placeholder for the conflict index.

    Example: '_%02d'  (generates _01, _02, etc.)

    If not specified, the default pattern '(%d)' is used.

  -H, --hidden
    Includes hidden files and directories in the search and renaming process.

    On Linux and macOS, hidden files are those that start with a dot character.
    On Windows, only files with the 'hidden' attribute are considered hidden.

    To match hidden directories as well, combine this with the -d/--include-dir
    flag.

  -d, --include-dir
    Includes matching directories in the renaming operation (they are excluded
    by default).

  -i, --ignore-case
    Ignores case sensitivity when searching for matches.

  -e, --ignore-ext
    Ignores the file extension when searching for matches.

  --json
    Produces JSON output, except for error messages which are sent to the
    standard error.

  -m, --max-depth
    Limits the depth of recursive search. Set to 0 (default) for no limit.

  --no-color
    Disables colored output.

  -D, --only-dir
    Renames only directories, not files (implies -d/--include-dir).

  -p, --pair
    Enable pair renaming to rename files with the same name (but different
    extensions) in the same directory to the same new name. In pair mode,
    file extensions are ignored.

    Example:
      Before: DSC08533.ARW DSC08533.JPG DSC08534.ARW DSC08534.JPG

      $ f2 -r "Photo_{%03d}" --pair -x

      After: Photo_001.ARW Photo_001.JPG Photo_002.ARW Photo_002.JPG

  --pair-order
    Order the paired files according to their extension. This helps you control
    the file to be renamed first, and whose metadata should be extracted when
    using variables.

    Example:
      --pair-order 'dng,jpg' # rename dng files before jpg
      --pair-order 'xmp,arw' # rename xmp files before arw

  --quiet
    Don't print anything to stdout. If no matches are found, f2 will exit with
    an error code instead of the normal success code without this flag.
    Errors will continue to be written to stderr.

  -R, --recursive
    Recursively traverses directories when searching for matches.

  -l, --replace-limit
    Limits the number of replacements made on each matched file. 0 (default)
    means replace all matches. Negative values replace from the end of the
    filename.

  --reset-index-per-dir
    Resets the auto-incrementing index when entering a new directory during a
    recursive operation.

  --sort
    Sorts matches in ascending order based on the provided criteria.

    Allowed values:
      * 'default'    : Lexicographical order.
      * 'size'       : Sort by file size.
      * 'natural'    : Sort according to natural order.
      * 'mtime'      : Sort by file last modified time.
      * 'btime'      : Sort by file creation time.
      * 'atime'      : Sort by file last access time.
      * 'ctime'      : Sort by file metadata last change time.
      * 'time_var'   : Sort by time variable.
      * 'int_var'    : Sort by integer variable.
      * 'string_var' : Sort lexicographically by string variable.

  --sortr
    Accepts the same values as --sort but sorts matches in descending order.

  --sort-per-dir
    Ensures sorting is performed separately within each directory rather than
    globally.

  --sort-var
    Active when using --sort/--sortr with time_var, int_var, or string_var.
    Provide a supported variable to sort the files based on file metadata.
    See https://f2.freshman.tech/guide/sorting for more details.

  -s, --string-mode
    Treats the search pattern (specified by -f/--find) as a literal string
    instead of a regular expression.

  -t, --target-dir
    Specify a target directory to move renamed files and reorganize your
    filesystem.

  -V, --verbose
    Enables verbose output during the renaming operation.

ENVIRONMENTAL VARIABLES
  F2_DEFAULT_OPTS
    Override the default options according to your preferences. For example,
    you can enable execute mode and ignore file extensions by default:

    export F2_DEFAULT_OPTS=--exec --ignore-ext

  F2_NO_COLOR, NO_COLOR
    Set to any value to disable coloured output.

  F2_DEBUG
    Enable debug mode.

LEARN MORE
  Read the manual at https://f2.freshman.tech