Skip to content

Commit

Permalink
docs: explain the strategy equivalent to the cherry-pick defaults (#110)
Browse files Browse the repository at this point in the history
  • Loading branch information
earl-warren committed Mar 30, 2024
1 parent ee7a87f commit b2e2e27
Showing 1 changed file with 13 additions and 3 deletions.
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,14 +74,24 @@ By default the tool will try to cherry-pick the single squashed/merged commit in

Based on the original pull request, creates a new one containing the backporting to the target branch. Note that most of these information can be overridden with appropriate CLI options or GHA inputs.

#### Default cherry-pick strategy
#### cherry-pick strategy

The default cherry-pick strategy is `recursive` with `theirs` option for automatic conflicts resolution. Therefore, by default, all commits are cherry-picked using the following git-equivalent command:
```bash
$ git cherry-pick -m 1 --strategy=recursive --strategy-option=theirs <sha>
```

From version `v4.2.0` we made both `strategy` and `strategy-option` fully configurable from CLI or GitHub action, so if users need a specific strategy which differs from the default one please consider using either `--strategy` or `--strategy-option`, or their equivalent GitHub action inputs, more details in [inputs](#inputs) section.
From version `v4.2.0` both can be configured via the `strategy` or `strategy-option` inputs if using the action and the `--strategy` or `--strategy-option` arguments if using the CLI.

The [default strategy](https://git-scm.com/docs/git-merge#Documentation/git-merge.txt--sltstrategygt) of the `git-cherry-pick` command is different from the defaults of `git-backporting`.
```bash
$ git cherry-pick -m 1 <sha>
```
is the same as:
```bash
$ git cherry-pick -m 1 --strategy=ort --strategy-option=find-renames <sha>
```
If there is a conflict the backport will fail and require manual intervention.

> **NOTE**: If there are any conflicts, the tool will block the process and exit signalling the failure as there are still no ways to interactively resolve them. In these cases a manual cherry-pick is needed, or alternatively users could manually resume the process in the cloned repository (here the user will have to resolve the conflicts, push the branch and create the pull request - all manually).
Expand Down Expand Up @@ -304,4 +314,4 @@ Every change must be submitted through a *GitHub* pull request (PR). Backporting

## License

Git backporting open source project is licensed under the [MIT](./LICENSE) license.
Git backporting open source project is licensed under the [MIT](./LICENSE) license.

0 comments on commit b2e2e27

Please sign in to comment.