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 not found, it will add the new preference.
     - **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
      ```

### Example Patch Files

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

-pref("browser.privatebrowsing.autostart", false);
+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 | Required | Purpose                             | Example                             |
| ----------- | ---------- | ------------------------------------- | ------------------------------------- |
| `i:`      | Yes      | Specifies the input file path.      | `i:/browser/app/profile/firefox.js` |
| `o:`      | Yes      | Specifies the output file path.     | `o:/browser/app/profile/firefox.js` |
| `t:`      | No       | Defines the type of patch.          | `t:pref`, `t:standard`, `t:new`, or `t:move`  |
| `+`       | Yes      | Adds a line to the output file.     | `+MOZ_APP_DISPLAYNAME=Spitfire`     |
| `-`       | Yes      | Removes a line from the input file. | `-MOZ_APP_DISPLAYNAME=Firefox`      |

### 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.