OSCAL Tips and Tricks
You do not have to a fork (in this context github.com/yourusername/OSCAL is a fork; github.com/usnistgov/OSCAL) and staff can create branches on the upstream repository. However, you may prefer to use your fork to prepare work before pushing to the upstream. If so, you may need to sync your develop and main branches from your fork with the upstream.
To follow this process there are important assumptions you make.
- The GitHub web interface has a sync branches feature for forks in our projects. This approach uses merge commits on the branches in the fork, and not 1:1 match of the branches. This strategy can lead to messier history history and potential conflicts later, we do not recommend doing this.
- Your fork is the
originremote, and the upstream usnistgov/OSCAL repo isupstream. - You do not make any changes you want to save your
developormainbranch in any circumstance. Following this guidance, they will be blown away.
To reset your fork's develop branch with the upstream develop, use the commands below.
$ git remote -v # If you results match below, you can skip the next few commands and skip to git fetch
origin git@github.com:yourusername/OSCAL.git (fetch)
origin git@github.com:yourusername/OSCAL.git (push)
upstream git@github.com:usnistgov/OSCAL.git (fetch)
upstream git@github.com:usnistgov/OSCAL.git (push)
$ git remote remove origin
$ git remote remove upstream # It may throw an error because it doesn't exist, this is to be safe.
$ git remote add upstream git@github.com:usnistgov/OSCAL.git
$ git remote add origin git@github.com:yourusername/OSCAL.git
$ git fetch --all # This is important or the next commands will reflect older "current" commits on the remotes, correct or incorrect.
$ git checkout --track origin/develop # first time
$ # Did you see the following error?
$ # 'fatal: A branch named 'develop' already exists.'
$ # If yes, you will do the command below after the first time.
$ git checkout develop # after first time
$ git reset --hard upstream/develop
$ git push origin develop -fTo reset your fork's main branch with the upstream main:
$ git remote -v # If you results match below, you can skip the next few commands and skip to git fetch
origin git@github.com:yourusername/OSCAL.git (fetch)
origin git@github.com:yourusername/OSCAL.git (push)
upstream git@github.com:usnistgov/OSCAL.git (fetch)
upstream git@github.com:usnistgov/OSCAL.git (push)
$ git remote remove origin
$ git remote remove upstream # It may throw an error because it doesn't exist, this is to be safe.
$ git remote add upstream git@github.com:usnistgov/OSCAL.git
$ git remote add origin git@github.com:yourusername/OSCAL.git
$ git fetch --all # This is important or the next commands will reflect older "current" commits on the remotes, correct or incorrect.
$ git checkout --track origin/main # first time
$ # Did you see the following error?
$ # 'fatal: A branch named 'develop' already exists.'
$ # If yes, you will do the command below after the first time.
$ git checkout main # after first time
$ git reset --hard upstream/main
$ git push origin main -fIf you are asked to make a pull request for an issue, you need to create a branch based off your target branch. Before you make a feature branch you likely need to make a rough sketch branch. The target may be the usnistgov/OSCAL develop branch, a feature- prefix branch, or main branch. You can approach this from 1 or 2 methods.
- Traditional Command Line Method with
git - GitHub Web Interface Method
You need to first ensure you have selected the correct target branch for the PR. In this case, in the example below, I will assume develop, not main.
$ git clone git@github.com:usnistgov/OSCAL.git
$ pushd OSCAL
$ git remote -v # Ensure below origin has usnistgov in the URL, if not use the correct remote alias if not origin
origin git@github.com:usnistgov/OSCAL.git (fetch)
origin git@github.com:usnistgov/OSCAL.git (push)
$ git checkout --track origin/develop # first time
$ # or if you see an error that branch develop already exists
$ git checkout develop # after first time
$ git fetch --all # ensure if you have done the above days or weeks again
$ git reset --hard origin/develop # IMPORTANT: you will delete uncommitted work on your local develop, but you should not use this or main anyway
$ git checkout -b name-for-new-pr-branch-targeting-develop
$ git push origin HEAD # or the appropriate remote aliasYou need to first ensure you have selected the correct target branch for the PR. In this case, in the example below, I will assume develop, not main.
- Open the relevant issue
- Open the create branch from issue menu on the lower right-hand side of the issue.
- Click the change branch source menu and choose the target
developbranch and click the Create Branch button.
- Follow clone instructions accordingly.
- Open the OSCAL repository on your workstation.
- Checkout your new branch from the target branch (
developormain):
$ git remote -v # confirm origin is usnistgov/OSCAL
me git@github.com:youruser/OSCAL.git (fetch)
me git@github.com:youruser/OSCAL.git (push)
origin git@github.com:usnistgov/OSCAL.git (fetch)
origin git@github.com:usnistgov/OSCAL.git (push)
$ git fetch --all
$ git checkout --track origin/develop
$ git checkout -b new-pr-to-develop # create PR branch
$ git push me HEAD # push to your fork
$ git submodule update --init --recursive
$ cd build/metaschema/
$ git fetch --all
$ git remote -v # confirm origin is usnistgov/metaschema-xslt
me git@github.com:youruser/metaschema-xslt.git (fetch)
me git@github.com:youruser/metaschema-xslt.git (push)
origin git@github.com:usnistgov/metaschema-xslt.git (fetch)
origin git@github.com:usnistgov/metaschema-xslt.git (push)
$ git checkout --track me/metaschema-fork-updated
$ cd ..
$ git submodule set-url build/metaschema git@github.com:youruser/metaschema-xslt.git
$ git add .gitmodules build/metaschema
$ git commit -m "[WIP] Test metaschema-xslt sub-module change to test tooling to fix model issue."