Working with Ferret as the upstream repository

The PyFerret repository is actually a branch (in the subversion repository at NOAA/PMEL) of the Ferret repository. PyFerret was given its own GitHub repository so that this branch would be more visible to the public. Also, the intention is eventually the PyFerret project will replace Ferret (but no scheduled time for this change has been decided).

To replicate this relationship between the Ferret and PyFerret repositories, the Ferret repository has been "merged" as an upstream repository to the PyFerret repository. (It would have been better to have created the PyFerret repository as a fork off the Ferret repository, but these repositories were originally populated using git svn with the subversion repository.)

After creating a local clone of the PyFerret repository, you can add the Ferret repository as an "upstream" repository using the git remote command such as:

<~/git/pyferret> % git remote add upstream git@github.com:NOAA-PMEL/Ferret.git

(This example uses the SSH address for the Ferret repository; you can also use the HTTPS address.) This command only adds the name upstream as a known remote site; nothing is uploaded at this time.

<~/git/pyferret> % git config --list
   ...
remote.origin.url=git@github.com:NOAA-PMEL/PyFerret.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
remote.upstream.url=git@github.com:NOAA-PMEL/Ferret.git
remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*

To merge changes made in the master branch of the Ferret repository into PyFerret, first fetch any updates in the Ferret respository:

<~/git/pyferret> % git fetch upstream

then merge the Ferret master branch into your current branch (presumably the PyFerret master branch)

<~/git/pyferret> % git merge --no-commit upstream/master
  ... (resolve any issues; inspect the code)
<~/git/pyferret> % git commit
<~/git/pyferret> % git push

Most often these merges will occur without incident, but there are some portions of PyFerret code where conflicts will arise (due to code divergence) and need to be resolved. On very rare occasions the merge will happen without incident, but examination of the changes show something was not done quite right. Often it is just duplication of a change, which probably is the result of the merge having previously been done through subversion and then pushed out to GitHub using git svn, but was not detected as the same change in the git merge. For this reason, adding the --no-commit flag in these merges is recommended so you can verify the changes before committing them.