Creating A Patch: what changed
Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | If you want to submit improvements to the FPC or Lazarus code, you need to submit a patch which developers can easily merge. | |
| 2 | 2 | ||
| 3 | - | ||
| 3 | + | Exceptions: | |
| 4 | 4 | ||
| 5 | - | ||
| 6 | - | ||
| 5 | + | 1. .po translation files should be sent as whole files | |
| 6 | + | 2. new files should be sent as whole files, with instructions where they should be placed | |
| 7 | 7 | ||
| 8 | 8 | ## Requirements | |
| 9 | 9 | ||
| 10 | - | ||
| 11 | - | ||
| 12 | - | ||
| 13 | - | ||
| 10 | + | You need the **main/development** version of Lazarus (or FPC). You can get Lazarus from GitLab repository. [[Getting Lazarus|Getting Lazarus development version]]. This is the native repository. | |
| 14 | 11 | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 12 | + | [](</File:Warning-icon.png>) | |
| 20 | 13 | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 14 | + | **Warning:** **If you submit patches, do _not_ base them on stable versions of Lazarus/FPC. Typically the development version is very different from stable versions as many improvements and fixes have been applied by the developers** | |
| 26 | 15 | ||
| 27 | - | ||
| 16 | + | [^Note]: The term **"main/development version of Lazarus"** appears to mean minor version number 99 (i.e., currently version 4.99, at the time of this writing), as per <https://wiki.lazarus.freepascal.org/index.php/Version_Numbering#Lazarus_3.0_and_newer>. | |
| 28 | 17 | ||
| 29 | 18 | ## Platform differences | |
| 30 | 19 | ||
| 31 | - | ||
| 20 | + | The instructions later assume you have opened a command prompt and moved (cd) to the directory of the repository. Here are the details: | |
| 32 | 21 | ||
| 33 | 22 | ### Windows | |
| 34 | 23 | ||
| 35 | - | ||
| 24 | + | Assuming you checked out Lazarus into C:\lazarus, open command prompt (cmd.exe) and type "cd \lazarus". | |
| 36 | 25 | ||
| 37 | 26 | ### *nix systems | |
| 38 | 27 | ||
| 39 | - | ||
| 28 | + | Assuming you checked out Lazarus into ~/lazarus, open terminal and type "cd ~/lazarus". | |
| 40 | 29 | ||
| 41 | - | ||
| 30 | + | ## Creating a patch using Git | |
| 42 | 31 | ||
| 43 | - | ||
| 44 | - | ||
| 32 | + | First, develop your code in a separate branch. While your development branch is active, you can create patches of all your local commits by : | |
| 45 | 33 | ``` | |
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 34 | + | git format-patch main | |
| 53 | 35 | ``` | |
| 54 | 36 | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 37 | + | It creates a set of patches named like "0001-CommitMsg.patch", "0002-CommitMsg.patch" and so on. | |
| 62 | 38 | ||
| 63 | - | ||
| 64 | - | ||
| 39 | + | If you want all the changes in one patch, either combine the commits using "git rebase -i ..." or use the following command : | |
| 65 | 40 | ``` | |
| 66 | - | ||
| 67 | - | ||
| 68 | - | ||
| 69 | - | ||
| 70 | - | ||
| 71 | - | ||
| 72 | - | ||
| 41 | + | git format-patch main --stdout > mypatch.patch | |
| 73 | 42 | ``` | |
| 74 | 43 | ||
| 75 | 44 | ## Submitting the patch | |
| 76 | 45 | ||
| 77 | - | ||
| 46 | + | Now you have a patch. I'd suggest to look the file over to see if it looks ok (no unexpected changes). | |
| 78 | 47 | ||
| 79 | - | ||
| 48 | + | The recommended way to submit a patch is through the [bug tracker](<http://bugs.freepascal.org>), see [[How do I create a bug report]] for details. If there is a report for the issue your patch fixes, use that, otherwise create a new issue. Upload the file to attach it to the issue. | |
| 80 | 49 | ||
| 81 | 50 | ## Git | |
| 82 | 51 | ||
| 83 | - | ||
| 52 | + | The GitHub repository [[1]](<https://github.com/graemeg/lazarus>) is only a mirror and does not accept pull-requests. | |
| 84 | 53 | ||
| 85 | 54 | ## Applying a patch | |
| 86 | 55 | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 56 | + | This explains how to apply somebody else's patch to your local repository. You can test the patch by using the --dry-run toggle switch like this: | |
| 101 | 57 | ``` | |
| 102 | - | ||
| 103 | - | ||
| 104 | - | ||
| 105 | - | ||
| 106 | - | ||
| 58 | + | patch --dry-run < somepatch.diff | |
| 107 | 59 | ``` | |
| 108 | 60 | ||
| 109 | - | ||
| 61 | + | The output of the patch program will be identical to the actual patching, only it does not alter the sourcecode files. Very handy for testing, without the possibility to screw up your source. | |
| 110 | 62 | ||
| 111 | 63 | ### A patch made with "git format-patch" | |
| 112 | 64 | ||
| 113 | 65 | #### Git | |
| 114 | 66 | ||
| 115 | - | ||
| 116 | - | ||
| 117 | - | ||
| 67 | + | Git itself applies the patch like this : | |
| 68 | + | ``` | |
| 118 | 69 | git apply 0001-gitpatch.patch | |
| 119 | 70 | ``` | |
| 120 | 71 | ||
| 121 | 72 | #### patch | |
| 122 | 73 | ||
| 123 | - | ||
| 124 | - | ||
| 125 | - | ||
| 74 | + | The "patch" command now supports git format patches with -p1. This is tested with patch v.2.6.1 on Linux, old versions may not support it. | |
| 75 | + | ``` | |
| 126 | 76 | patch -p1 < 0001-gitpatch.patch | |
| 127 | 77 | ``` | |
| 128 | 78 | ||
| 129 | - | ||
| 79 | + | "patch" is available for Windows, too, but there are also GUI tools for the job. | |
| 130 | 80 | ||
| 131 | 81 | #### TortoiseMerge | |
| 132 | 82 | ||
| 133 | - | ||
| 83 | + | TortoiseMerge supports the Git format patch without problems. It is installed together with Tortoise SVN but is not integrated in explorer. It must be opened from the Start menu. | |
| 134 | 84 | ||
| 135 | - | ||
| 85 | + | ToDo: add more GUI tools that support Git format patches | |
| 136 | 86 | ||
| 137 | 87 | ### Troubleshooting | |
| 138 | 88 | ||
| 139 | - | ||
| 140 | - | ||
| 141 | - | ||
| 89 | + | Finally, patches may have a Unix/Linux line ending (LF) while your local file has Windows (CR+LF) line endings or vice versa. You'll have to convert the patch file before applying on Windows at least, as the supplied patch.exe is picky about line endings. | |
| 142 | 90 | ||
| 143 | - | ||
| 91 | + | On Windows, the patch.exe supplied with FPC/Lazarus is very picky; you may have better luck with the patch.exe supplied by Git: | |
| 92 | + | ``` | |
| 144 | 93 | "C:\Program Files (x86)\Git\bin\patch.exe" -p0 < mypatch.diff | |
| 145 | 94 | ``` | |
| 146 | 95 | ||
| 147 | - | ||
| 148 | - | ||
| 149 | 96 | ## See also | |
| 150 | 97 | ||
| 151 | - | ||
| 152 | - | ||
| 153 | - | ||
| 154 | - | ||
| 98 | + | * [[How do I create a bug report]] general information on submitting bugs, what should be covered in a bug report, and using the bug tracker. | |
| 99 | + | * [[Tips on writing bug reports]] detailed information on what should be covered in a bug report. | |
| 100 | + | * [[Database bug reporting]] Specific info and sample programs for database bugs | |
| 101 | + | * [[Moderating the bug tracker]] | |
| 155 | 102 | ||
| 156 | 103 | --- | |
| 157 | - | ||
| 104 | + | *From the Free Pascal wiki, page "Creating A Patch", as the Internet Archive kept it on 2025-12-20, last changed on 2025-02-23. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |