Docs: update (#1338)

.github/workflows/gh-pages.yml

@@ -18,6 +18,7 @@ on:
         description: 'Git ref (refs/heads/<branch>, refs/tags/<tag>, etc.) or SHA'
         required: true
         type: string
+        default: 'refs/heads/main'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

docs/output/cleaning.md

@@ -1,9 +1,22 @@
 # Output Directory Cleaning
 
-The `igir clean` [command](../commands.md) can be used when writing (`igir copy`, `igir move`, and `igir link`) to delete files from the `--output <path>` directory that are either:
+The `igir clean` [command](../commands.md) can be used when writing (`igir copy`, `igir move`, and `igir link`) to delete files from the `--output <path>` directory that were _not_ considered for writing.
 
-- Not contained in any provided [DAT](../dats/introduction.md) (the [`--dat <path>` option](../dats/processing.md#scanning-for-dats)).
-- Contained in a [DAT](../dats/introduction.md) (the [`--dat <path>` option](../dats/processing.md#scanning-for-dats)), but the file is in the incorrect location.
+!!! note
+
+    The term "considered" is used here because output files that already exist won't be [overwritten](options.md#overwriting-files) by default. These output file paths were _considered_ for writing, but then Igir chose _not_ to write them.
+
+Only files from [`--input <path>` directories](../input/file-scanning.md) can be used when writing to the `--output <path>` directory. Therefore, the output files that will be cleaned (because they _weren't_ considered for writing) are files that:
+
+- (When using [DATs](../dats/introduction.md)) Don't [match](../roms/matching.md) any ROM in any DAT
+- Were filtered out by [filter options](../roms/filtering-preferences.md#filters)
+- Were filtered out by [1G1R preferences](../roms/filtering-preferences.md#preferences-for-1g1r)
+
+!!! warning
+
+    Because only input files will be considered for writing to the output directory, you will want your input files to be a superset of your output files. In other words, if a file isn't in your input files, it will be cleaned from your output directory.
+
+    It is a [best practice](../usage/best-practices.md#file-inputs) to include your output directory as an input directory when cleaning files. This will ensure any previously written valid files won't be cleaned.
 
 ## The golden rule
 

docs/roms/filtering-preferences.md

@@ -390,6 +390,12 @@ The `--single` option is required for all `--prefer-*` options, otherwise there
 
 Multiple `--prefer-*` options can be specified at once, and they will be applied in the following order of importance (most important to least important).
 
+!!! warning
+
+    Be careful when using the `igir move` command! 1G1R preferences are only applied to files found & matched in the input directories. Because moving files will change what files are in your input directories, different games may be preferred if you run the same command multiple times.
+
+    It is a [best practice](../usage/best-practices.md#file-inputs) to include your output directory as an input directory when moving files. This will ensure any previously moved games remain the preferred version when applying 1G1R rules again.
+
 ### Prefer game names
 
 ```text

docs/usage/best-practices.md

@@ -16,7 +16,7 @@ While [DATs](../dats/introduction.md) are optional, they allow you to organize y
 
 **Use consistent versions across all devices.**
 
-DATs work best if you store them alongside your primary ROM collection, and when you use the same DAT versions across all devices (i.e. your primary collection, handhelds, flash carts, etc.). Some DAT groups release new versions as often as daily, so keeping your collection in sync is easier with consistent DATs.
+DATs work best if you store them alongside your primary ROM collection and when you use the same DAT versions across all devices (i.e. your primary collection, handhelds, flash carts, etc.). Some DAT groups release new versions as often as daily, so keeping your collection in sync is easier with consistent DATs.
 
 **Process DATs from different groups separately.**
 
@@ -32,6 +32,13 @@ Provide your output directory as one of the input directories, and then any othe
 
 Then, create sub-collections by copying files from your main collection to other devices, optionally applying [filtering and preference rules](../roms/filtering-preferences.md).
 
+**Provide the output directory as an input directory when moving or cleaning.**
+
+This is for a few reasons:
+
+- [1G1R rules](../roms/filtering-preferences.md#preferences-for-1g1r) are only applied to files found & matched in the input directories, so moving files out of the input directories may change your 1G1R results on subsequent runs. Providing the output directory as an input directory will make sure you keep your preferred files.
+- The [`igir clean` command](../output/cleaning.md) excludes files considered for writing (either written or _not_ [overwritten](../output/options.md#overwriting-files)). Providing the output directory as an input directory will ensure no DAT-matched files are deleted.
+
 **Prefer ROMs with headers.**
 
 Igir can [remove headers automatically](../roms/headers.md#automatic-header-removal) when needed, but it cannot add them back. Keep ROMs with headers in your primary collection and then modify them when copying to other devices as needed.
@@ -54,7 +61,7 @@ Zip files generally save file space and are faster to scan, at the expense of mo
 
 Ignoring [arcade ROM sets](../usage/arcade.md), one purpose of sorting your ROM collection using DATs is to organize them in some human-understandable manner. A common way to help with this is to group ROMs from the same console together using [`--dir-dat-name`](../output/path-options.md#append-dat-name) or [`--dir-dat-description`](../output/path-options.md#append-dat-description)`
 
-Alternatively, you can [filter to only the DATs](../dats/processing.md#dat-filtering) you want, and then [combine them together](../dats/processing.md#dat-combining) and write the resulting ROMs to one directory.
+Alternatively, you can [filter to only the DATs](../dats/processing.md#dat-filtering) you want and then [combine them](../dats/processing.md#dat-combining) and write the resulting ROMs to one directory.
 
 **Organize ROMs by letter for non-keyboard & mouse devices.**
 
@@ -76,7 +83,7 @@ You must choose the right DAT for your emulator (e.g. MAME) and emulator version
 
 **For MAME, use the official DATs or ones from progetto-SNAPS.**
 
-These DATs provide the most flexibility (i.e. can use any merge type) and the most amount of metadata (i.e. [parent/clone information](../dats/introduction.md#parentclone-pc-dats), ROMs and CHDs together in one DAT) for Igir to use for processing. Other DAT groups such as pleasuredome modify the official DATs quite heavily by pre-applying filters.
+These DATs provide the most flexibility (i.e. can use any merge type) and the most amount of metadata (i.e. [parent/clone information](../dats/introduction.md#parentclone-pc-dats), ROMs & CHDs together in one DAT) for Igir to use for processing. Other DAT groups such as pleasuredome modify the official DATs quite heavily by pre-applying filters.
 
 **Pick a ROM merge type intentionally.**