Skip to content

Usage

Jump to bottom
saltkid edited this page Jan 15, 2024 · 11 revisions

Usage

gorn [command] <args> [--flags] <args>
gorn [--switch] <args>
  1. Commands
    • Commands dictate the behavior of gorn and are required to be able to rename media files
  2. Switches
    • Switches are flags that switch the behavior of gorn from its default behavior of renaming media files
  3. Flags
    • Flags modifies the behavior of gorn when renaming media files.

Commands

1. root

  • values: <path/to/root/dir>

This will rename all series and movies in the root directory based on directory naming and structure.

Example:

gorn root path/to/root/dir

The episode numbers per entry/season/part will be padded to 2 digits and will start at 01. movies will be named based on the directory they are in. Naming scheme will vary depending on the type of media which gorn will detect:

  • standalone movie, movie set
  • single season, multiple seasons, and named parts/seasons. all with or without movies

For more information about different naming schemes per media type, go to scheme

User can specify multiple root/source directories to rename.

gorn root path/to/root/dir root path/to/another/root/dir

2. series and movies

  • values: <path/to/source/dir>

User can specify series and movie source dirs separately. User can also specify multiple source dirs. Other than that, it shares the same default renaming behavior as specifying a root dir.

Examples:

gorn series path/to/series/source/dir

gorn movies path/to/movies/source/dir

gorn root path/to/root/dir -s path/to/another/series/source/dir -m path/to/another/movies/source/dir

Notes:

  • user should specify at least one root, series, or movies dir
  • there are validations to check:
    1. if the dir path exists
    2. if multiple dir paths are specified, checks if they are unique
    3. if multiple dir paths are specified, checks if they are not subdirs of each other

Switches

1. --help

  • short form: -h
  • values: <commands>, <switches>, <flags>, no value
  • default: none

Shows the simple help message. If user inputted a flag right after --help, it will show the detailed help message for that specific flag.

Example:

gorn -h --naming-scheme

gorn --help --help

2. --version

  • short form: -v
  • values: none
  • default: none

Shows the welcome message along with the version.

Example:

gorn -v

gorn --version

Flags

Flags have default values if they are not specified. This is different from the default value if a flag is specified but without a value.

  • if --keep-ep-nums is not specified, it still has a default value (false).
  • if --keep-ep-nums is specified without a value, it will have its default value (true).

1. --keep-ep-num

  • short form: -ken
  • values: var, no value
  • default if ommitted: false
  • default if no value: true

By default, episode numbers are padded to 2 digits and will start at 01. These are automatically generated and renames the files based on natural sorting.

If this flag is present, gorn will keep the original episode numbers in the filename based on common naming patterns. If none was found in the filename, it will not rename for that specific file.

This can be useful if you only have episodes that are canon, aka you don't have filler episodes, so you want to keep the episode number already in the filename.

If this flag is set to var, gorn will ask for user input whether or not to keep the episode numbers again:

  • per series type level
  • per series entry level (if inputted var on per series type level)
  • per series season level (if inputted var on per series entry level)

Example:

gorn -ken root path/to/root/dir

gorn --keep-ep-num var root path/to/root/dir

2. --starting-ep-num

  • short form: -sen
  • values: <num>, var
  • default if ommitted: 1
  • default if no value: none, will error

By default, episode numbers are padded to 2 digits and will start at 01. You can specify a different starting number to start at by --starting-ep-num <num>.

If this flag is set to var, gorn will ask for user input again on what starting episode number to start at:

  • per series type level
  • per series entry level (if inputted var on per series type level)
  • per series season level (if inputted var on per series entry level)

Example:

gorn -sen 5 root path/to/root/dir

gorn --starting-ep-num var root path/to/root/dir

3. --has-season-0

  • short form: -s0
  • values: var, no value
  • default if ommitted: false
  • default if no value: true

By default, the media files in specials/extras directory under a series entry will be ignored and are not renamed.

If the flag is present, gorn will rename the files in the specials/extras directory under a series entry, treating it as season 0.

Note that if the flag is present, there must be ONE special/extras directory under the series entry. If there are multiple, it won't rename the files and inform the user. Otherwise, there can be any number of specials/extras directories

If this flag is set to var, gorn will ask for user input again on whether or not to rename the files in the specials/extras directory as season 0 under a series entry:

  • per series type level
  • per series entry level (if inputted var on per series type level)
  • no input for per series season level since var is not allowed in per series entry level

Example:

gorn -s0 root path/to/root/dir

gorn --has-season-0 var root path/to/root/dir

4. --options

  • short form: -o
  • values: none
  • default: none

By default, gorn will populate flags with default values if they are ommitted. This is on an all media level.

--options flag will ensure the flags are not populated with default values when ommitted. Since there will be no values, the user will be prompted to input them either during:

  • per series type level
  • per series entry level (if inputted var on per series type level)
  • per series season level (if inputted var on per series entry level)

Example:

gorn -o root path/to/root/dir

gorn --options root path/to/root/dir

5. --logs

  • short form: -l
  • values: none, <log-header>, no value
  • default if ommitted: info
  • default if no value: info

By default, gorn will print out INFO, WARN, and FATAL logs to the console. You can override this by --logs <log-header>

Note: user can add a postfix -only to a header argument for --logs to only print that header's logs

Log Header Meanings

  1. FATAL: errors that cannot be safely skipped and will interrupt process
  2. WARN: errors that can be safely skipped
  3. INFO: informational logs
  4. TIME: logs for timing processes; for performance purposes

Log Levels based on Headers

  1. FATAL: FATAL logs only
  2. WARN: WARN and FATAL logs
  3. INFO: INFO, WARN, and FATAL logs
  4. TIME: TIME, INFO, WARN, and FATAL logs

Example:

gorn -l root path/to/root/dir

gorn --logs time-only root path/to/root/dir

6. --naming-scheme

  • short form: -ns
  • values: "<scheme>", default, var
  • default if ommitted: default
  • default if no value: none, will error

By default, gorn will rename the files differently based on the type of media. User can override this by --naming-scheme "<scheme>" or --naming-scheme var.

"<scheme>" overrides the naming scheme for all media files regardless of type (series only; movies will ignore these additional options)

If the flag is set to var, gorn will ask for user input again on the naming scheme:

  • per series type level
  • per series entry level (if inputted var on per series type level)
  • per series season level (if inputted var on per series entry level)

Example:

gorn --naming-scheme var root path/to/root/dir

gorn -ns "S<season_num>E<episode_num> <parent: '\d+\.\s*([^(]*)\(.*$'> <p-2: 1,5>" root path/to/root/dir

scheme

scheme can be composed of any character (as long as its a valid filename) and/or APIs enclosed in <> like:

  • S<season_num>E<episode_num>
    • output: S01E01
  • S<season_num>E<episode_num> - <parent-parent> <parent> static text
    • output: S01E01 - Fruits Basket Season 1 static text

Naming Scheme APIs

Current APIs are:

  1. <season_num>

    • represents the season number which is based on series type, and directory structure and naming
    • additional option: padding with 0s
      • <season_num: 2> which pads the result to 2 digits
      • <season_num: 3> which pads the result to 3 digits
      • etc ...

  2. <episode_num>

    • represents the episode number which is either:
      • read from the filename
      • generated based on the --keep-ep-nums and --starting-ep-num flags
    • additional option: padding with 0s just like <season_num>

  3. <parent>

    • represents the parent directory of the media file.
    • if no option was specified, it will copy the whole name of the parent directory
    • additional option: select the range of characters from the parent directory name
    • it can be:
      • a range of two numbers like <parent: 0,3>
        • <parent: 0,3> which will copy the first 4 characters of the parent directory name
      • a single number like <parent: 4>
        • <parent: 4> which will copy the 5th character of the parent directory name
      • a regex enclosed in single quotes like <parent: 'S(\d+)'>
        • <parent: 'S(\d+)'> which will copy the capture group (\d+) that is prepended by S from the parent directory name. Notes:

          1. it can only have one capture group per part

          2. each part is separated by outermost pipes |

          3. ie. S(\d+)|E(\d+) is valid. It has one capture group per part and has 2 parts

          4. ie. S(E|\d+) has one capture group and one part. | inside parenthesis does not count as a part separator. only | outside parenthesis is part separator

          5. ie. 'S(E)(\d+)|S(\d+) is invalid since the first part has 2 capture groups, even if the second part has only 1

    • another additional option is going above just the parent of the current directory.

      • <parent-parent> which will copy the parent of the parent directory

      • <parent-parent: 0,4> which will copy the first 4 characters of the parent of the parent directory

      • <parent-parent-parent> which will copy the parent of the parent of the parent directory

      • <p>: short form. <p> is equivalent to <parent> in every way

      • <p-2>: you can specify how much further up the directory tree you want to go by appending a number

      • <p-2> is equivalent to <parent-parent> in every way

  4. <self>

    • same as parent but instead of being based on the parent directory name, it is based on the name of the media file before renaming it
    • additional options are the same as well except for <p-number>. self has no short form
Clone this wiki locally