|
| 1 | +# Git Cherry-pick update for Downstream Repos |
| 2 | + |
| 3 | +`git cherry-pick` is a handy tool to directly apply specific commits from one branch or repo to another even when they don't share a git history—especially when you do not want to merge large change sets. This can be helpful when forking another repo or building off an evolving template, such as this guide. Below, we provide a step-by-step guide to updating repositories based on the template guide repo: |
| 4 | + |
| 5 | +!!! tip "Be Prepared!" |
| 6 | + Before you start, you should know which commits are going to be pulled from the template repo. Collect their hashes in a separate text file; be sure to list them in chronological order, so they can be applied correctly. |
| 7 | + |
| 8 | +1. **Ensure the target repo is up-to-date.** |
| 9 | +2. Create a new branch onto which to pull the changes: |
| 10 | + |
| 11 | + ```console |
| 12 | + git checkout -b dev |
| 13 | + ``` |
| 14 | + |
| 15 | +3. Check the remotes available for your repo: |
| 16 | + |
| 17 | + ```console |
| 18 | + git remote -v |
| 19 | + ``` |
| 20 | + |
| 21 | + !!! note |
| 22 | + If you haven't updated yet, you will only see the current repo options (`origin`): |
| 23 | + |
| 24 | + ```console |
| 25 | + origin [email protected]:Imageomics/Imageomics-guide.git (fetch) |
| 26 | + origin [email protected]:Imageomics/Imageomics-guide.git (push) |
| 27 | + ``` |
| 28 | + |
| 29 | + In which case, run the following to add the template guide as an available remote under the title `upstream`: |
| 30 | + |
| 31 | + ```console |
| 32 | + git remote add upstream [email protected]:Imageomics/Collaborative-distributed-science-guide.git |
| 33 | + ``` |
| 34 | + |
| 35 | + After running `git remote -v`, you should then see |
| 36 | + |
| 37 | + ```console |
| 38 | + origin [email protected]:Imageomics/Imageomics-guide.git (fetch) |
| 39 | + origin [email protected]:Imageomics/Imageomics-guide.git (push) |
| 40 | + upstream [email protected]:Imageomics/Collaborative-distributed-science-guide.git (fetch) |
| 41 | + upstream [email protected]:Imageomics/Collaborative-distributed-science-guide.git (push) |
| 42 | + ``` |
| 43 | + |
| 44 | +4. Run `git fetch upstream` to get the commits from the template repo (now recognized as `upstream`). |
| 45 | +5. Run `git cherry-pick --edit <first-commit-hash>`, this way, the URL pointing to the Collaborative Distributed Science Guide can be modified to function properly from the downstream repo. Ex: |
| 46 | + |
| 47 | + ```console |
| 48 | + git cherry-pick --edit a3d2f5d621aaa5b9a543fabad3f813ceb45964d4 |
| 49 | + ``` |
| 50 | + |
| 51 | + The next screen should provide the commit message for editing: |
| 52 | + |
| 53 | + ```console |
| 54 | + Update GitHub Repo Archiving Guidance (#29) |
| 55 | + |
| 56 | + * Add section on automatically maintaining metadata on Zenodo |
| 57 | + ... |
| 58 | + ``` |
| 59 | + |
| 60 | + press ++i++, then, using arrow keys to navigate the console edit the message to the following: |
| 61 | + |
| 62 | + ```console |
| 63 | + Update GitHub Repo Archiving Guidance |
| 64 | + |
| 65 | + Pull from Collab Guide [PR 29](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/29) |
| 66 | + |
| 67 | + * Add section on automatically maintaining metadata on Zenodo |
| 68 | + ... |
| 69 | + ``` |
| 70 | + |
| 71 | + The URL will render as "[Imageomics/Collaborative-distributed-science-guide#29](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/29)", with the functional hyperlink. Finally, select ++esc++ and type `:wq` to complete the commit message edit. |
| 72 | + |
| 73 | + !!! info "Conflicts Happen" |
| 74 | + If you have a merge conflict, open the file, resolve the conflict, and then `git add` the file. From that point you should be able to run `git cherry-pick --continue` and it will provide the commit message from the upstream. Checking `git status` and `git log` at various points in this process will allow you to check on how these are progressing and see the addition of the upstream commits to your current repo's branch. |
| 75 | + |
| 76 | +6. Once you've collected all the upstream commits, run `git push --set-upstream origin dev` to add them to the current repo. |
| 77 | +7. Open a pull request from the `dev` branch to add these upstream commits to `main`. Be sure to include a description of the commits, where they came from, and include links to PRs _from the upstream repo_. Auto-links generated by GitHub (based on `#<issue/PR-number>`) will link to that number issue or PR in the current repo, not the upstream one. |
| 78 | + |
| 79 | +8. Rebase commit the PR. This allows for the changes pulled from upstream to be seamlessly integrated into the downstream repo. The commit hashes are not preserved across repositories, so there is no information to lose. |
| 80 | + |
| 81 | +See also [`git cherry-pick`](https://git-scm.com/docs/git-cherry-pick) for more info on available options. |
0 commit comments