Skip to content

Git Notes Getting Started

Jump to bottom Edit New page
Isaac Leventon edited this page Dec 8, 2025 · 54 revisions

Overview

  1. Fork the NIST-FRG/cone-db repo
  2. Checkout the main branch
  3. ** Setup the remote upstream repo (firemodels)* *
  4. Make changes in your local repo
  5. Stage your changes (git add)
  6. Commit your changes
  7. Push your changes to your GitHub repo (origin)
  8. Submit a pull request to NIST-FRG/cone-db
  9. Accept or cancel the pull request (if you are a project member).

Introduction

There are several ways to contribute to a project with Git. Since most of the current collaborators on this project are "newbies" to Git, the purpose of this Wiki is to prevent "wild west" code slinging by setting some guidelines for workflow. These are guidelines, not laws. This guideance is based on the workflow used by the Fire Dynamics Simulator (FDS) development team. Following this workflow adds a level of quality assurance to the project. Notes describing how to perform specific tasks using Git are given here.

The Git guru is Scott Chacon. Here is a link to his Pro Git book. Chapter 2 on Git basics and chapter 3 on branching are especially useful. And here is a link to his long YouTube video Introduction to Git. There is a ton of information here.

Another resource is this Git course by Software Carpentry.

The step-by-step instructions below are meant to distill most of this down to a workflow we can all follow. Let us know if something does not work right.

Getting Started

Install Git on your local machine

Mac and Linux users will likely already have Git installed. To confirm this, open a terminal and type

$ git --version
git version 2.51.2

To install Git for Windows go here.

Create a GitHub account

If you do not already have one, create a GitHub account.

Do some local configuration

You will need to set your Git configuration so that the remote server knows who you are when you are pushing.

$ git config --global user.name "John Doe"            # need not be GitHub username
$ git config --global user.email john.doe@example.com # same as GitHub account
$ git config --global color.ui true

Windows users may need to add the following to their configuration file. In theory, the .gitattributes file should take care of this. However, if you are a Windows user and upon cloning the repo and doing a git status you immediately see modified files this is most likely due to problems with line endings. To solve this problem, first delete the repository (see removing repositories), then add the following to your git configuration,

$ git config --global core.autocrlf true

and finally clone your fork again (see "Clone the forked repos" below). Cd to the repo directory and do another git status; hopefully there are no modified files.

Fork repos from NIST-FRG

Go to the NIST FRG organization GitHub page. For each project you want to work with, fork the corresponding repo(s) over to your GitHub account by clicking the fork icon on the upper right. If you cannot find this repository, please email Isaac.Leventon@nist.gov and share your Github username to request access. You will now have a copy of the cone-db repo in <username>/<cone-db> on GitHub.

Clone the forked repos

The repo you will work from is now in your space on GitHub. To get this repo to your computer you need to clone it. There are a few ways to do this. For example, see the "Clone to Desktop" and "Download Zip" buttons to the right side of your project page or using the Github Desktop Application, as described below. Alternatively, to use the command line SSH clone, please review the instructions available on the FDS Wiki

Cloning from within GitHub Desktop

This method is ideal if you already have the application open. Using the github desktop application to clone our original repo can often help with security/login issues.

  1. Open GitHub Desktop and make sure you're logged in.
  2. Go to the top menu bar and select File, then click Clone Repository.
  3. In the "Clone a Repository" window click the GitHub.com or GitHub Enterprise tab to see a list of your available repositories. Click the desired repository from the list.
  4. Make sure your local path looks something like: ..\Github\NIST-FRG\
  5. Click the Clone button at the bottom of the window to start the process.
  6. Once cloned, you will have a full local copy of the repository.GitHub Desktop can help you sync changes (push and pull) between your local and the remote version but we'd prefer you follow the worflow below (e.g., using the Git Bash Terminal).

###########

IMPORTANT: Repo names cannot be changed because many relative paths are hardwired into the scripts in the project.

Therefore, we recommend you create a directory to put all your forked repositories. Below I will assume you have created a folder called NIST-FRG to hold all the repos associated with the project.

Now, let's see what you've got. Change directories into your repository directory and list your local branches.

$ cd NIST-FRG/cone-db/
$ git branch
* master

What this tells you is that your local fds repo has one branch master and that this is the branch you are currently on (*). The default naming for your version of Github may use 'main' instead of 'master'.

Now let's look at what branches exist in your remote repo.

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

remotes/origin/HEAD is a pointer to the tip of your current branch (don't worry about that for now). remotes/origin/origin is the default branch. This was the branch that was cloned to your machine.

Now the confusing bit: how does your local master branch stay up-to-date with the NIST-FRG/cone-db master branch? We have to do one more thing: add an upstream tracking branch to pull from.

Staying up-to-date with the central repo

First, check your remote state. You should see no "upstream" repositories. The only remote repo you should see is origin.

$ git remote -v
origin	git@github.com:username/cone-db.git (fetch)
origin	git@github.com:username/cone-db.git (push)

If you see "upstream" repos in addition to origin, then you need to remove them.

$ git remote rm <repo-name>

Add tracking for NIST-FRG/cone-db.

$ git remote add upstream git@github.com:NIST-FRG/cone-db.git
$ git fetch upstream
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 6 (delta 4), reused 5 (delta 3), pack-reused 0
Unpacking objects: 100% (6/6), done.
From github.com:firemodels/fds
 * [new branch]      master -> firemodels/master

$ git remote -v
firemodels	git@github.com:firemodels/fds.git (fetch)
firemodels	git@github.com:firemodels/fds.git (push)
origin	git@github.com:rmcdermo/fds.git (fetch)
origin	git@github.com:rmcdermo/fds.git (push)

Now look at your branches.

$ git branch -a
* master
  remotes/firemodels/master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

remotes/firemodels are the branches from the firemodels/fds repo. remotes/origin are the branches in your GitHub repo. We will see how to merge these later (via pull requests). master is your LOCAL branch.

Authentication issues?

If you see an error message, like: "git@github.com: Permission denied (publickey)", then you need to generate a new SSH key and add it to github. Run this in Git Bash or WSL (PowerShell is ok too):

$ ssh-keygen -t ed25519 -C "your_email@example.com"

When prompted for a file, hit Enter to save to the default:

/c/Users/<username>/.ssh/id_ed25519

Enter a passphrase [or empty/just hit enter for no passphrase]. Once complete, you should see:

Your identification has been saved in /c/Users/itl2/.ssh/id_ed25519

Your public key has been saved in /c/Users/itl2/.ssh/id_ed25519.pub

Open the .pub file in a text exitor, copy the text, and add this key to GitHub. Go to your profile on github.com after logging in. Click settings, SSH and GPG keys, New SSH key. Paste the contents of your .pub file. Check that this worked by returning to bash; if you type the command below, you should see:

$ ssh -T git@github.com
Hi <username>! You've successfully authenticated, but GitHub does not provide shelcess.

Updating your repository

To get all the changes committed by other project members to the central repo, do the following:

$ git remote update
Fetching origin
Fetching upstream
$ git checkout master              # make sure you are in your master branch
$ git diff upstream/master       # see what is different in your development branch
$ git merge upstream/master      # merge any changes from the central repo
From git@github.com:NIST-FRG/cone-db.git
 * branch            master -> FETCH_HEAD
Already up-to-date.

Your LOCAL repo will now have changes made to NIST-FRG/cone-db. However, your GitHub repo will still be behind. You need to push the changes up to GitHub.

$ git push origin master

Tracking multiple repositories

Central to the philosophy of Git is that no particular repo is special. Of course, when we release the code we need to have a traceable source tree, hence the NIST-FRG repo. But there is no reason we cannot view and share code between each other without going through the NIST-FRG hub. To do this we simply need to add other remote repositories for tracking.

If you are on the NIST-FRG/cone-db GitHub page and click on contributors then Members you can see a list of other GitHub users who have forked the firemodels/fds repo.

Do another remote add:

$ git remote add <gituser> git@github.com:<gituser>/cone-db.git
$ git remote update
Fetching origin
Fetching upstream
Fetching <gituser>
From git@github.com:<gituser>/fds
 * [new branch]      master -> <gituser>/master

Now have a look at your branches.

$ git branch -a
* master
  remotes/NIST-FRG/master
  remotes/<gituser>/master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

You can now easily fetch and merge any changes made by <gituser>.

Making changes

Complete this section on making changes, submitting/approving PRs tomorrow

Add a custom footer
Add a custom sidebar

Clone this wiki locally