Creating A Patch: what changed

Revision 2 to 3. 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	5		1. .po translation files should be sent as whole files
6	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	10		You need the main/development version of Lazarus (or FPC). You can get Lazarus using either Git or SVN.
11	11
12	12		- Git: [[Getting Lazarus\|Getting Lazarus development version]]. This is the native repository.
13	13		- SVN: Read-only mirror of the official GitLab repository requires some svn gymnastics due to a bug in many versions of svn:
14	14
15		-	~~`svn checkout --depth files `[`https://github.com/fpc/Lazarus/branches`](https://github.com/fpc/Lazarus/branches)` all`\~~
16		-	~~`cd all`\~~
17		-	~~`svn update --set-depth infinity main`~~
	15	+	```text
	16	+	svn checkout --depth files https://github.com/fpc/Lazarus/branches all
	17	+	cd all
	18	+	svn update --set-depth infinity main
	19	+	```
18	20
19		-	~~`svn checkout --depth files `[`https://github.com/fpc/FPCSource/branches`](https://github.com/fpc/FPCSource/branches)` all`\~~
20		-	~~`cd all`\~~
21		-	~~`svn update --set-depth infinity main`~~
	21	+	```text
	22	+	svn checkout --depth files https://github.com/fpc/FPCSource/branches all
	23	+	cd all
	24	+	svn update --set-depth infinity main
	25	+	```
22	26
23	27		> 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
24	28
25	29		## Platform differences
26	30
27	31		The instructions later assume you have opened a command prompt and moved (cd) to the directory of the repository. Here are the details :
28	32
29	33		### Windows
30	34
31	35		Assuming you checked out Lazarus into C:\lazarus, open command prompt (cmd.exe) and type "cd \lazarus".
32	36
33	37		### *nix systems
34	38
35	39		Assuming you checked out Lazarus into ~/lazarus, open terminal and type "cd ~/lazarus".
36	40
37	41		## Creating a patch using SVN
38	42
39	43		``` bash
40	44		svn diff > mypatch.diff
41	45		```
42	46
43	47		This includes all changed files in the whole SVN repository.
44	48
45	49		You can also define the individual files, to make sure no garbage is included, eg. :
46	50
47	51		``` bash
48	52		svn diff ide/main.pp ideintf/objectinspector.pp > mypatch.diff
49	53		```
50	54
51	55		> Note: If using [TortoiseSVN](http://tortoisesvn.tigris.org/) on Windows, you can select the folder where Lazarus was checked out in Windows Explorer then right click to select TortoiseSVN-\>Create Patch...
52	56
53	57		See also [[TortoiseSvn\|TortoiseSvn#Troubleshooting]] if you have problems.
54	58
55	59		## Creating a patch using Git
56	60
57	61		First, develop your code in a separate branch! While your development branch is active, you can create patches of all your local commits by :
58	62
59	63		``` bash
60	64		git format-patch master
61	65		```
62	66
63	67		It creates a set of patches named like "0001-CommitMsg.patch", "0002-CommitMsg.patch" and so on.
64	68
65	69		If you want all the changes in one patch, either combine the commits using "git rebase -i ..." or use the following command :
66	70
67	71		``` bash
68	72		git format-patch master --stdout > mypatch.patch
69	73		```
70	74
71	75		## Submitting the patch
72	76
73	77		Now you have a patch. I'd suggest to look the file over to see if it looks ok (no unexpected changes).
74	78
75	79		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.
76	80
77	81		## Git
78	82
79	83		The GitHub repository [1](https://github.com/graemeg/lazarus) is only a mirror and does not accept pull-requests.
80	84
81	85		## Applying a patch
82	86
83	87		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:
84	88
85	89		``` bash
86	90		patch --dry-run < somepatch.diff
87	91		```
88	92
89	93		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.
90	94
91	95		### A patch made with "svn diff"
92	96
93	97		To do the final patching, use the following commandline:
94	98
95	99		``` bash
96	100		patch < somepatch.diff
97	101		```
98	102
99	103		If that doesn't work because the path layout of your environment is different from the environment where the patch was created, you can tell patch to strip out all path information:
100	104
101	105		``` bash
102	106		patch -p0 < somepatch.diff
103	107		```
104	108
105	109		Any GUI tool for diffs on Windows can handle these patches, too, including TortoiseMerge.
106	110
107	111		### A patch made with "git format-patch"
108	112
109	113		#### Git
110	114
111	115		Git itself applies the patch like this :
112	116
113	117		``` bash
114	118		git apply 0001-gitpatch.patch
115	119		```
116	120
117	121		#### patch
118	122
119	123		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.
120	124
121	125		``` bash
122	126		patch -p1 < 0001-gitpatch.patch
123	127		```
124	128
125	129		"patch" is available for Windows, too, but there are also GUI tools for the job.
126	130
127	131		#### TortoiseMerge
128	132
129	133		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.
130	134
131	135		ToDo: add more GUI tools that support Git format patches
132	136
133	137		### Troubleshooting
134	138
135	139		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.
136	140
137	141		On Windows, the patch.exe supplied with FPC/Lazarus is very picky; you may have better luck with the patch.exe supplied by Git:
138	142
139	143		```dos
140	144		"C:\Program Files (x86)\Git\bin\patch.exe" -p0 < mypatch.diff
141	145		```
142	146
143	147		... or the svn patch command available since SVN 1.7.
144	148
145	149		## See also
146	150
147	151		- [[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.
148	152		- [[Tips on writing bug reports]] detailed information on what should be covered in a bug report.
149	153		- [[Database bug reporting]] Specific info and sample programs for database bugs
150	154		- [[Moderating the bug tracker]]
151	155
152	156		---
153	157		From the Free Pascal wiki, page "Creating A Patch", as it stood on 2022-01-13 after a change by Trev, out of the wiki's dump of 2024-05-26. 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).

Back to history