GitHub workflow

github_workflow.md

GitHub: Recommended workflow to contribute to an external project

Initial setup

1. Fork the project on GitHub.

2. Clone the forked repository.

3. Add the original GitHub repository as a new remote named upstream to the cloned repository:

   git remote add upstream git@github.com:ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
   git remote update upstream --prune

Contribute to the upstream project

1. Create a new branch in the cloned repository, ideally named after the kind of changes you want to contribute (like add-FEATURE-XYZ; here we'll use NEW-BRANCH-NAME as a placeholder):

   git checkout -b 'NEW-BRANCH-NAME'
   git push --set-upstream origin 'NEW-BRANCH-NAME'

2. Commit all your changes to that branch and push them eventually.

3. Create a pull request on GitHub for the upstream project to incorporate your changes. You can use the official GitHub CLI gh to do this on the command line. To open GitHub's pull request web interface, run:

   gh pr create --web

4. If you need to refine the pull request by making additional changes, just commit and push them to the same NEW-BRANCH-NAME. The GitHub pull request will thereby automatically be updated.

5. After your pull request has successfully been merged into the original GitHub repository, you might want to clean up and delete the corresponding branch in your fork (locally and remotely):

   git checkout master
   git push origin --delete 'NEW-BRANCH-NAME'
   git branch --delete 'NEW-BRANCH-NAME'

   Note: Use git branch --delete --force 'NEW-BRANCH-NAME' to delete the local branch even if it hasn't been (fully) merged into its upstream branch.

   Source: https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely/

Other useful operations

Update the cloned repository / sync upstream changes

To incorporate changes from the master branch of the upstream repository into the master branch of the cloned one, do the following:

git fetch upstream
git checkout master
git merge upstream/master
git push

Update the list of upstream branches

To update the local list of the remote upstream branches displayed by git branch --all, do the following:

git remote update upstream --prune

Source: https://stackoverflow.com/a/36358502/7196903

Clone a specific remote branch without fetching the whole repository

To clone the specific remote branch upstream/BRANCH-NAME only, do the following:

git clone --single-branch --branch BRANCH-NAME upstream

Source: https://stackoverflow.com/questions/1911109/how-do-i-clone-a-specific-git-branch/

Make an existing local branch track a specific remote branch

To make the local branch FORSAKEN-BRANCH track the remote branch upstream/SOME-BRANCH, do the following:

git branch --set-upstream-to=upstream/SOME-BRANCH FORSAKEN-BRANCH

Source: https://stackoverflow.com/questions/520650/make-an-existing-git-branch-track-a-remote-branch/

More information

• Syncing a fork