From 78786d6d90632c783d353b27f745d49861bc19c4 Mon Sep 17 00:00:00 2001 From: Bozydar Szadkowski Date: Tue, 5 Sep 2023 14:40:48 -0400 Subject: [PATCH] Update working with patches doc Fixed a few typos, updated the procedure, and formatted the doc. Test: N/A Bug: b/266660664 Change-Id: I94df37b84099e678150db809b199465c2bdefbce GitOrigin-RevId: 0722528a7ab93d6957600d89dab836327a6610cd --- third_party/patches/README.md | 68 +++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/third_party/patches/README.md b/third_party/patches/README.md index 97bcda42..4713286d 100644 --- a/third_party/patches/README.md +++ b/third_party/patches/README.md @@ -1,23 +1,35 @@ # Working with patches -Patch files are used to apply the changes to repositories imported with Bazel's [`http_archive`](https://docs.bazel.build/versions/main/repo/http.html) rule. +Patch files are used to apply the changes to repositories imported with Bazel's +[`http_archive`](https://docs.bazel.build/versions/main/repo/http.html) rule. ## Generating the patch files -The patch files are generated with `git diff` commmand which displays the diff between the workspace and the last committed version. +The patch files are generated with `git diff` command which displays the diff +between the workspace and the last committed version. -Typical worklfow for generating the patch files is described on example of `llvm` repository below. The repository is imported into reclient WORKSPACE from https://github.com/llvm/llvm-project/. `WORKSPACE` file defines the commit that should be downloaded [here](https://github.com/bazelbuild/reclient/tree/main/WORKSPACE;l=47). +Typical workflow for generating the patch files is described on example of +`llvm` repository below. The repository is imported into reclient WORKSPACE from +https://github.com/llvm/llvm-project/ and +[`settings.bzl`](https://github.com/bazelbuild/reclient/tree/main/settings.bzl) +file defines the commit that should be downloaded. To generate the patch file, the user should: -1. Clone the remote repository by running `git clone https://github.com/llvm/llvm-project/` -2. Checkout the same commit that's imported by reclient (e.g. `git checkout 39e2e3bddbf459d16b00969af1415ebee11fcbdc`) -3. Make the necessary changes in `llvm-project` respository -4. Generate the patch file by running `git diff > /third_party/patches/.patch` +1. Clone the remote repository by running `git clone + https://github.com/llvm/llvm-project/` +1. Checkout the same commit that's imported by reclient (e.g. `git checkout + 39e2e3bddbf459d16b00969af1415ebee11fcbdc`) +1. Make the necessary changes in `llvm-project` repository +1. Generate the patch file by running `git diff > + /third_party/patches/.patch` ## Applying patches -Patches are applied after `http_archive` extracts the archive. To add the patch that you'd like to apply, add it to patches argument of `http_archive` rule. Example: +Patches are applied after `http_archive` extracts the archive. To add the patch +that you'd like to apply, add it to patches argument of the `http_archive` rule. +Example: + ``` ... patch_args = ["-p1"], @@ -27,18 +39,38 @@ patches = [ ], ... ``` + **Notes:** -1. `patch_args = ["-p1"]` is required when applying patch files generated by `git diff` command. (see [`http_archive` documentation](https://docs.bazel.build/versions/main/repo/http.html) for more details). -2. Patches are applied in the same order as they're declared in the `patches` argument (`patches = ["//1.patch", "//2.patch"]` may produce different results than `patches = ["//2.patch", "//1.patch"]`). + +1. `patch_args = ["-p1"]` is required when applying patch files generated by + `git diff` command. (see + [`http_archive` documentation](https://docs.bazel.build/versions/main/repo/http.html) + for more details). +1. Patches are applied in the same order as they're declared in the `patches` + argument (`patches = ["//1.patch", "//2.patch"]` may produce different + results than `patches = ["//2.patch", "//1.patch"]`). ## Updating the patched repository -Sometimes, especially after updating the version imported by `http_archive` rule, applying existing patches may fail. In such cases it's useful to try to apply the patch in your local repository and manually fix the changes that were rejected by following steps below (`llvm` repo used as an example): -1. Clone the remote repository by running `git clone https://github.com/llvm/llvm-project/` -2. Checkout the same commit that's imported by reclient (e.g. `git checkout 39e2e3bddbf459d16b00969af1415ebee11fcbdc`) -3. Try to apply the patch with `git apply --reject --whitespace=fix /third_party/patches/.patch`. If the command failed to apply some of the changes, `.patch.rej` file will be generated. -4. Review the content of `.patch.rej` file and apply the changes manually -5. Remove `.patch.rej` -6. Generate updated patch file by running `git diff > /third_party/patches/.patch` +Sometimes, especially after updating the version imported by `http_archive` +rule, applying existing patches may fail. In such cases it's useful to try to +apply the patch in your local repository and manually fix the changes that were +rejected by following steps below (`llvm` repo used as an example): + +1. Clone the remote repository by running `git clone + https://github.com/llvm/llvm-project/` +1. Checkout the same commit that's imported by reclient (e.g. `git checkout + 39e2e3bddbf459d16b00969af1415ebee11fcbdc`) +1. Try to apply the patch with `git apply --reject --whitespace=fix + /third_party/patches/.patch`. If the + command failed to apply some of the changes, `.patch.rej` file + will be generated. +1. Review the content of `.patch.rej` file and apply the changes + manually +1. Remove `.patch.rej` +1. Generate updated patch file by running `git diff > + /third_party/patches/.patch` -**Note:** Please note that the order of patches matters and they should be applied in the same order that they were declared in the `patches` parameter of `http_archive` rule. \ No newline at end of file +**Note:** Please note that the order of patches matters and they should be +applied in the same order that they were declared in the `patches` parameter of +`http_archive` rule.