diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/index.rst | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/doc/user/index.rst b/doc/user/index.rst index fdca7bd..13e61bf 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -4,26 +4,28 @@ User docs This page contains information useful to people who want to use the .patch files generated by patchtree. -.. note:: - - By convention, the patch file should be placed in the root of the target directory under the filename ``.patchtree.diff``. - This allows you to easily revert and/or upgrade the patch later. - -.. important:: - - If you keep the target directory under version control, make sure the repository root is the same as the root of the patch's target directory. - Patches produced by patchtree contain *extended header lines* which are be interpreted by ``git apply``. - Because these header lines must include the path to each modified file relative to the repository root, any files which don't exist at the expected location will be skipped silently by ``git``. +.. _user_apply: **************** Applying a patch **************** -To apply patches output by patchtree, download the ``.patch`` file and place it in the directory where it should apply the changes under the name ``.patchtree.diff``. +#. Download the ``.patch`` file for your source tree and place it in the directory where it should apply +#. Rename the downloaded file to ``.patchtree.diff`` +#. Open Git bash (on Windows) or any shell (if on \*NIX) in the directory with the patch +#. Mark the patch as executable by running:: + + $ chmod +x .patchtree.diff + +#. Apply the patch by running:: + + $ ./.patchtree.diff -To apply the patch, run the following command in the target directory:: +If all goes well, this command should produce no output and the source files will have been updated. +In case the patch fails to apply without producing any output, the above command can be ran with the ``-v`` option to produce verbose output. +Any command-line options recognized by git-apply(1) can also be used. - $ git apply .patchtree.diff +.. _user_revert: ***************** Reverting a patch @@ -31,7 +33,7 @@ Reverting a patch To revert the changes of a patch, run the following command in the target directory:: - $ git apply --reverse .patchtree.diff + $ ./.patchtree.diff --reverse ***************** Upgrading a patch @@ -39,6 +41,5 @@ Upgrading a patch Upgrading a patch consists of -#. reverting the current (old) patch -#. downloading and replacing the ``.patchtree.diff`` file with the new patch -#. reapplying the patch file +#. `Reverting the current (old) patch <user_revert_>`_ +#. Repeating the steps from :ref:`user_apply` using the new patch file |