Git Cherry-pick update for Downstream Repos¶

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 the Collaborative Distributed Science Guide. Below, we provide a step-by-step guide to updating repositories based on updating this repo from the template guide:

Be Prepared!

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.

Ensure the target repo is up-to-date.
Create a new branch onto which to pull the changes:
```
git checkout -b dev
```

Check the remotes available for your repo:

git remote -v

Note

If you haven't added the template repo as a remote yet, you will only see the current repo options (origin):

origin  git@github.com:Imageomics/Imageomics-guide.git (fetch)
origin  git@github.com:Imageomics/Imageomics-guide.git (push)

In which case, run the following to add the template guide as an available remote under the title upstream:

git remote add upstream git@github.com:Imageomics/Collaborative-distributed-science-guide.git

After running git remote -v, you should then see

origin  git@github.com:Imageomics/Imageomics-guide.git (fetch)
origin  git@github.com:Imageomics/Imageomics-guide.git (push)
upstream    git@github.com:Imageomics/Collaborative-distributed-science-guide.git (fetch)
upstream    git@github.com:Imageomics/Collaborative-distributed-science-guide.git (push)

Run git fetch upstream to get the commits from the template repo (now recognized as upstream).
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:
```
git cherry-pick --edit a3d2f5d621aaa5b9a543fabad3f813ceb45964d4
```
The next screen should provide the commit message for editing:
```
Update GitHub Repo Archiving Guidance (#29)

* Add section on automatically maintaining metadata on Zenodo
...
```
press I, then, using arrow keys to navigate the console edit the message to the following:
```
Update GitHub Repo Archiving Guidance

Pull from Collab Guide [PR 29](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/29)

* Add section on automatically maintaining metadata on Zenodo
...
```
The URL will render as "Imageomics/Collaborative-distributed-science-guide#29", with the functional hyperlink. Finally, select Esc and type :wq to complete the commit message edit.

Conflicts Happen

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.
Once you've collected all the upstream commits, run git push --set-upstream origin dev to add them to the current repo.
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.
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.

See also git cherry-pick for more info on available options.