[[applying-patches]]
= Applying Patches

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


If a patch is received on a JIRA ticket, then it should be reviewed and applied using command line tools.

== Inspect the patch

First, take a look at what changes are in the patch.
You can do this easily with `git apply`

[source,bash]
----
git apply --stat CAUSEWAY-xxx.patch
----

Note that this command does not apply the patch, but only shows you the stats about what itâ€™ll do.
After peeking into the patch file with your favorite editor, you can see what the actual changes are.

Next, you're interested in how troublesome the patch is going to be.
Git allows you to test the patch before you actually apply it.

[source,bash]
----
git apply --check CAUSEWAY-xxx.patch
----

If you don't get any errors, the patch has no conflicts.
Otherwise you may see what trouble youâ€™ll run into.

== Apply a (clean) patch

To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:

[source,bash]
----
git am --signoff < CAUSEWAY-xxx.patch
----

This preserves the original author's commit message.

However, this can fail if the patch file does not contain the original committers email address.
In this case you will need to abort the `am` session:

[source,bash]
----
git am abort
----

and continue on by applying a non-clean patch, as described next.

== Apply a (non-clean) patch

If the patch does not apply cleanly, then the original authors commit message cannot be preserved.
This sequence in this case is:

[source,bash]
----
git apply CAUSEWAY-xxx.patch
----

Fix up any issues.
The add and commit as usual

[source,bash]
----
git add .
git commit -am "<original authors' commit message>" --signoff
----

The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.

Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].

== Diff files

If a diff file has been provided instead of a patch, then use for example the eGit's wizards (Eclipse's Git integration).
