Skip to content

Using Git

Jump to bottom
Stephen Frank edited this page Oct 9, 2013 · 8 revisions

Using Git

GitHub hosts the code repository for the Campus Energy Modeling project using Git.

Installing Git

Git builds for Windows, Linux, and Mac are available from the Git website. Since Git is a distributed version control system, each local installation is a complete repository. All versions of Git include built-in a graphical user interface (GUI) in addition to the command line tools. Third party GUI clients are also available, including GitHub's native clients: GitHub for Windows and GitHub for Mac.

After installing Git (on Windows), you can access the Git shell environment and GUI via either the Start menu or the right-click popup menu on folders in Windows File Explorer. First time users should read the Getting Started chapter in Pro Git and the GitHub setup guide. For more documentation and training materials, see Documentation.

Accessing the Repository

Access to the repository is available via either HTTPS or SSH. You can also browse the repository online at https://github.com/NREL/CampusEnergyModeling. You must have a GitHub account and be added to the NREL GitHub group and CampusEnergyModeling project in order to view the repository.

Prior to cloning the repository, you must set up Git with your name and email:

git config --global user.name "Your Name Here"
git config --global user.email "your_email@nrel.gov"

HTTPS Access

Setup instructions for access via HTTPS:

  1. Launch Git bash.
  2. Navigate to the local directory where the repository will be created.
  3. Execute git clone https://github.com/NREL/CampusEnergyModeling.git.

Read access via HTTPS does not require a password. However, if you execute git push, you must enter your GitHub password.

SSH Access

Setup instructions for access via SSH:

  1. Launch Git bash.
  2. Navigate to the local directory where the repository will be created.
  3. Execute git clone git@github.com:NREL/CampusEnergyModeling.git. You now have read access.
  4. To get write access, you must generate an SSH key and tell Git about it; follow these instructions.

GitHub Native Client

GitHub for Windows and GitHub for Mac users can access the repository using the Clone in Desktop button on the Campus Energy Modeling homepage.

Best Practices

Please adhere to the following development practices when working with the repository:

  • Use frequent, small commits to keep code changes isolated and make them easy to track
  • Write useful commit messages
  • Keep the repository clean
    • Do not commit binary files.
    • Do not commit compiled libraries (except when absolutely necessary).
    • Do not keep multiple copies of the same file, "old" config files, etc. If you need to save multiple versions of your work, use Git branches instead.
    • Do not commit automatically generated files, such as EnergyPlus output files.
  • Push working code
    • Use your local repository for development, then push to the GitHub when your code is functional.
    • Alternatively, create and use a feature development branch to keep your broken code out of dev.

See also our Git Workflow.

Documentation

To learn Git, please consult the following resources:

Heavy developers may wish to consult Using OpenStudio with Git and GitHub (a guide to using Git for development with NREL's OpenStudio project), much of which applies to the Campus Energy Modeling project as well.

Finally, Google and Stack Overflow are your friends.

Clone this wiki locally