Patcher/README.md

<p align="center">
  <img src="https://weforge.xyz/Spitfire/Branding/raw/branch/main/active/search/icon-alt4.svg" alt="Logo" width="64" height="64">
</p>

<p align="center" style="font-size: 32px;">
  <strong>Spitfire Patcher</strong>
</p>

<p align="center">
This is a custom patcher for applying modifications to Firefox source code. It processes patch files located in the `./patches` directory and applies them to files in a specified root path.
</p>

## How to Use

1. Place your patch files in the `./patches` directory. Example of patch file:

   ```patch
   i:/browser/branding/official/configure.sh
   o:/browser/branding/official/configure.sh

   -MOZ_APP_DISPLAYNAME=Firefox
   +MOZ_APP_DISPLAYNAME=Spitfire
   ```
2. Run the patcher with the `--path` and `--patches` flags:

   ```sh
   ./run.sh --path ./mozilla-central/obj-x86_64-pc-linux-gnu/dist/bin --patches ./mozilla-central/patcher/post-compile-patches
   ```

- --path *Will be resolved to an absolute path, and patches will be applied relative to this path.*
- --patches *Specifies a path to a `.patch` file or a folder containing patches to be applied by this script*

## Parameters Explained

Here are the details of each parameter used in the patching system:

### **`i:` (Input)**

- Specifies the input file to which the patch should be applied.
- This is the file that will be read and modified based on the patch instructions.
- **Example:**

  ```patch
  i:/browser/branding/official/configure.sh
  ```

  - This means the input file is located at `/browser/branding/official/configure.sh`.

### **`o:` (Output)**

- Specifies the output file where the modified content will be saved.
- If the input and output paths are the same, the original file will be overwritten.
- **Example:**

  ```patch
  o:/browser/branding/official/configure.sh
  ```

  - This means the output file is `/browser/branding/official/configure.sh`.

### **`t:` (Type)**

- Defines the type of patch being applied. This parameter can be skipped if not applicable.
- Common types:
  1. **`standard`:** Standard patching type that follows the `+` (add) and `-` (remove) syntax.
     - Used for general file modifications.
     - **Example:**
       ```patch
       i: /browser/branding/official/configure.sh
       o: /browser/branding/official/configure.sh

       -MOZ_APP_DISPLAYNAME=Firefox
       +MOZ_APP_DISPLAYNAME=Spitfire
       ```
      Note: *Type will fallback to t:standard when no type is specified.*

  2. **`pref`:** Indicates that the patch is modifying preference settings (e.g., Firefox `prefs.js`).
     - When `t:pref` is specified, the script will search for existing preferences in the input file and replace them with the new ones provided in the patch. If a preference is not found, it will be added to the end of the file.
     - **Example:**
       ```patch
       t:pref
       i:/browser/branding/nightly/pref/firefox-branding.js
       o:/browser/branding/nightly/pref/firefox-branding.js

       +pref("extensions.getAddons.showPane", false); // HIDDEN
       ```
  3. **`new`:** Used for creating new files or overwriting existing files with specified content.
     - Creates a new file at the `o:` location.
     - **Example:**
       ```patch
       t:new
       o:/browser/branding/official/newfile.txt

       +This is a new file created by Spitfire Patcher.
       ```
  4. **`copy`:**: Copies files or directories from the input path to the output path, overwriting if necessary.
     - Copies the contents of a file or directory from i: to o:.
     - **Example:**
       ```patch
       t:copy
       i:/patcher/pre-compile-patches/branding
       o:/browser/branding/official
       ```
  5. **`marker`:** Modifies a file relative to a specific marker line.
      - A line starting with # defines the marker.
      - Lines starting with + are inserted immediately after the marker.
      - Lines starting with - are removed from the file (after the marker).
      - **Example:**
      ```patch
      t:marker
      i:/browser/locales/en-US/firefox-l10n.js
      o:/browser/locales/en-US/firefox-l10n.js

      #static const RedirEntry kRedirMap[] =
      +    {"store", "http://localhost:20351/",
      +     nsIAboutModule::ALLOW_SCRIPT |
      +         nsIAboutModule::URI_MUST_LOAD_IN_CHILD |
      +         nsIAboutModule::URI_CAN_LOAD_IN_PRIVILEGEDABOUT_PROCESS},
      ```

### Example Patch Files

```patch
t:pref
i:/browser/firefox.js
o:/browser/spitfire.js

+pref("browser.privatebrowsing.autostart", true);
```

```patch
t:standard
i:/browser/app/profile/firefox.js
o:/browser/app/profile/firefox.js

-MOZ_APP_DISPLAYNAME=Firefox
+MOZ_APP_DISPLAYNAME=Spitfire
```

```patch
t:new
o:/browser/branding/official/new-file.txt

+Welcome to Spitfire Browser Branding.
```

### Summary of Parameters

| Parameter |  Purpose                             | Example                             |
| ----------- | ------------------------------------- | ------------------------------------- |
| `i:`      | Specifies the input file path.      | `i:/browser/app/profile/firefox.js` |
| `o:`      | Specifies the output file path.     | `o:/browser/app/profile/firefox.js` |
| `t:`      | Defines the type of patch.          | `t:pref`, `t:standard`, `t:new`, `t:marker`  |
| `+`       | Adds a line to the output file.     | `+MOZ_APP_DISPLAYNAME=Spitfire`     |
| `-`       | Removes a line from the input file. | `-MOZ_APP_DISPLAYNAME=Firefox`      |
| `#`       | Marks a reference line for insertion (used in `marker` type). | `#    'settings',`               |

### Workflow

1. **Define Input and Output:** Use `i:` and `o:` to specify which files to read and write.
2. **Specify Patch Type:** Use `t:` for special handling like preference modifications.
3. **Apply Modifications:** Use `+` to add lines and `-` to remove lines.