Confirmed users
1,927
edits
Bugzilla:Patches: Difference between revisions
→Using diff
mNo edit summary |
|||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
After you've written your code, the next thing to do is to make a patch! This | After you've written your code, the next thing to do is to make a patch! This page will show exactly what changes you made to Bugzilla or its documentation, in a format that we can review and integrate into our codebase. | ||
We also call patches "diffs", because one program used for making patches is called " | We also call patches "diffs", because one program used for making patches is called "diff”. | ||
= Using git = | |||
If you installed Bugzilla from the tarball, it's | We are transitioning to [[Bugzilla:Git|git]] for our source | ||
control. Basic usage is very similar to bzr, but there are different | |||
concepts and workflows. '''This is the preferred way of making patches.''' | |||
Git is very powerful, but anything beyond simple use is greatly aided | |||
by an understanding of the whole system. One of the best references is | |||
the book [http://git-scm.com/book Pro Git], which is available for | |||
free in its entirety. | |||
The following sections outline some simple workflows; for further | |||
details, see the Pro Git book or any of the numerous tutorials and | |||
references available online. | |||
== The Simple Way: Local uncommitted changes == | |||
After cloning the Bugzilla repo and switching to your desired branch, | |||
the simplest way to generate a diff is to just make local | |||
modifications and use '''git diff''' in that branch. This way should | |||
only be used if you’re making simple modifications to a couple files | |||
and only working on one patch at a time. | |||
If you’ve only modified or removed existing files, then this is all you need: | |||
git diff > patch.diff | |||
This will not catch any new files, since git doesn’t know if you | |||
really wanted to add them or if they are just left over from something | |||
else, e.g. building. If you want new files included in your patch, | |||
then you need to run '''git add''' on them. However, in this case, | |||
you’ll ''also'' have to run '''git add''' on any ''modified'' files and | |||
'''git rm''' on any deleted files. This is because once you’ve | |||
"staged" changes to be committed (added your new files), you have to | |||
tell git about any other changes you want to commit as well. Finally, | |||
you’ll have to add --cached to the '''git diff''' command. See the | |||
chapter of Pro Git on | |||
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository recording changes to the git repository] for more details. | |||
You can then upload "patch.diff" as your patch. | |||
== The Better Way: Local development branches == | |||
If you are intending to do any complicated changes, or if you want to | |||
work on more than one patch at a time, or if you just want to do | |||
things the typical git way, you’re going to want to create local | |||
branches for your work. | |||
After cloning, change to the branch you want to base your work | |||
on. Create and switch to a new, local branch by running | |||
git checkout -b <branch_name> | |||
Replace ''branch_name'' by something descriptive, e.g. bug-123456 or | |||
fix-headers. You might want to include the base branch name as well, | |||
particularly if you are doing the same fix to multiple branches. | |||
At this point, you can add, modify, and remove files ''and commit as often as you like''. Because git branches are cheap and easy to throw | |||
away, you don't need to be careful about crafting one tidy | |||
commit. Even if you have commit permissions and will be pushing your | |||
changes to the main git repository yourself, you can still squash | |||
commits together later via '''git rebase''' before merging into the | |||
base branch. | |||
Once you have completed your work, make sure all your changes are | |||
committed, then run | |||
git diff <base_branch> > patch.diff | |||
Replace ''base_branch'' by the name of the branch off of which your | |||
local branch is based, e.g. master, 4.4, 4.2, etc. This will produce a | |||
diff of all changes you committed since you branched; upload | |||
"patch.diff" as your patch. | |||
You can even "rebase" your local branch to update it with changes that | |||
have been done upstream to your base branch by other developers--or | |||
even by yourself in another branch. This is out of scope for this simple | |||
tutorial, but see the chapter in Pro Git on | |||
[http://git-scm.com/book/en/Git-Branching branching] for lots more | |||
info, including details on standard git work flows. | |||
= Using Bzr = | |||
If you [[Bugzilla:Bzr|checked Bugzilla out of bzr]], then you can make patches using bzr. | |||
== The Simple Way: '''<code>bzr diff</code>''' == | |||
The simplest way to make a patch from your current bzr checkout is like this: | |||
<pre>bzr diff > patch.diff</pre> | |||
And that's it. Then you can upload "patch.diff" as your patch. | |||
== If Your Patch Contains Renames: '''<code>bzr bundle</code>''' == | |||
If your patch contains renames, then you have to use the '''<code>bzr bundle</code>''' command to produce your patch. To create a bundle: | |||
# first you have to locally commit your changes: <pre>bzr commit --local -m 235423</pre> There "235423" was the id of the bug I was working on. That's just a fake "commit message" for this patch, it doesn't really matter what I put there. | |||
# Then create the bundle: <pre>bzr bundle bzr://bzr.mozilla.org/bugzilla/trunk > patch.bundle</pre> There, "bzr://bzr.mozilla.org/bugzilla/trunk" is the branch that I'm creating this bundle against. The bundle will, in most cases, only work against that branch. | |||
Then you can attach the bundle just like a normal patch. When you upload it, note that it's a bundle in its description. For example, you might call it "v1 (bundle)". | |||
=== Applying Bundles === | |||
If you have a bundle and you want to apply it to your local installation, you can do it like this: | |||
# Apply the bundle: <pre>bzr merge path/to/patch.bundle</pre> | |||
# Remove the fake "commits" that were created while creating the bundle: <pre>bzr revert --forget-merges</pre> | |||
And now you have a checkout with the bundle applied, but without any of the "commits" involved in the bundle. | |||
== Moving, Adding, and Deleting Files == | |||
Before you make your patch, if you have added, moved, or renamed files, you will have to run certain commands so that those files will show up in your patch. | |||
* If you have '''added''' files, you can use '''<code>bzr add</code>''' to add them: <pre>bzr add ''path/to/file''</pre> Doing '''<code>bzr add</code>''' on a directory will add that directory and all files in it. Doing '''<code>bzr add</code>''' all by itself, with no arguments, will add every unknown file in your checkout. | |||
* If you have '''removed''' files, you don't ''have'' to do anything to make them disappear from your patch. However, if you want, you can use '''<code>bzr rm</code>''' to remove directories or files and also explicitly notify bzr that they're gone. | |||
* To rename a file, use '''<code>bzr mv</code>'''. If you've already renamed a file and you just want bzr to know that you renamed it, you can use '''<code>bzr mv --after</code>'''. (Or sometimes, just typing '''<code>bzr mv --auto</code>''' all by itself will have bzr automatically "figure out" if you've moved a file.) | |||
= Using CVS = | |||
Before Bugzilla used Bazaar, it used CVS, and if you installed Bugzilla from the tarball, it's set up so that you can make diffs against CVS. | |||
1. Change to your Bugzilla directory: | 1. Change to your Bugzilla directory: | ||
| Line 17: | Line 136: | ||
Where ''new-file-name'' is the name of the file you added. | Where ''new-file-name'' is the name of the file you added. | ||
Alternately, you can also add files to your patch by using the "cvsdo" program on *nix or [http://viper.haque.net/~timeless/redbean/cvsdo.pl cvsdo.pl] on Windows. Before you do the "cvs diff" in step 2 above, do: | |||
cvsdo add ''new-file-name'' | |||
(Except on Windows, that would be "cvsdo.pl" or "perl.exe cvsdo.pl" instead of just "cvsdo".) | |||
= Using diff = | |||
Sometimes, for various reasons, you can't use CVS. In this case, you can get the difference between two Bugzilla ''directories'', one which contains the base Bugzilla, and one which contains your modified Bugzilla. | Sometimes, for various reasons, you can't use git, bzr, or CVS. In this case, you can get the difference between two Bugzilla ''directories'', one which contains the base Bugzilla, and one which contains your modified Bugzilla. | ||
Here's how to use diff to make a patch: | Here's how to use diff to make a patch: | ||
| Line 27: | Line 150: | ||
2. Now, Bugzilla contains lots of things that you ''don't'' want to diff, like the localconfig file and the data/ directory. So you want to exclude all of those from your diff. Here's a command that will do that: | 2. Now, Bugzilla contains lots of things that you ''don't'' want to diff, like the localconfig file and the data/ directory. So you want to exclude all of those from your diff. Here's a command that will do that: | ||
diff -Nru --exclude=data --exclude='*.orig' --exclude=CVS --exclude=localconfig --exclude=.htaccess --exclude='.#*' --exclude='*.rej' ''old/'' ''new/'' > patch.diff | diff -Nru --exclude=data --exclude='*.orig' --exclude=CVS --exclude=localconfig --exclude=.bzr --exclude=.htaccess --exclude='.#*' --exclude='*.rej' ''old/'' ''new/'' > patch.diff | ||
Where ''old/'' is the base Bugzilla before your modifications, and ''new/'' is the Bugzilla that you modified. | Where ''old/'' is the base Bugzilla before your modifications, and ''new/'' is the Bugzilla that you modified. | ||