Basic git tutorial
Git is a distributed version control system (DVCS), where each developer has their own copy of the project and periodically pulls in other users changes and pushes their own. GitHub is a website that hosts git repositories and offers ways to interact with the repo.
There are many resources online to help you learn Git and GitHub. Here is a short list to get you started.
Git -- the Simple Guide from Roger Dudler.
Getting Started with Git from Tania Rascia.
Git Documentation from the Git.
Hello World from GitHub guides.
NREL uses Git version control for the four repositories used to build the System Advisor Model (SAM).
The local repository is the one stored on your computer. The remote repository is the one stored at GitHub.com. To make a contribution to SAM, first make a local copy on your computer of the remote repository on GitHub. That process is called "cloning."
-
Create a folder on your computer to store the local repositories, for example
/sam_dev. -
Open a terminal, and go to the folder where you want to store the repositories, for example
/sam_dev. -
Use Git to clone SAM's four code repositories.
cd path/to/sam_dev
git clone https://github.com/NREL/lk.
git clone https://github.com/NREL/wex
git clone https://github.com/NREL/ssc
git clone https://github.com/NREL/SAM
Note that the clone command creates a folder fore the repository. In this case, it will create lk, wex, ssc, and SAM folders in sam_dev, so you do not need to create those folders.
A branch is a separate version of a repository that you create for your code contribution. When your work on the contribution is finished, merge your branch back into the main repository.
The NREL SAM team uses the develop branch for work on the SAM repositories. During periods when we are working on revisions (or "patches") to a current version, we also maintain a patch branch. If your contribution is a new feature or bug fix, you should work off of the develop branch. Only work off of the patch branch if you are fixing a bug for a revision to a current version. (If you do work off of patch, you should merge patch into develop when your work is finished.)
-
Open a terminal, and go to the repository you plan to contribute to.
-
Check the status of the repository to see if there are any differences between your local copy and the remote.
-
Update the local branch with any changes that have been made on the remote since you cloned or last updated the repository.
-
Create a branch off of
developfor your work.
cd path/to/sam_dev/SAM
git checkout develop
git status
git pull
git branch <branch_name>
Merging is the process of incorporating your contribution into the main repository after you finish your work. A pull request is a mechanism for asking other programmers to review and approve your code.
-
Run tests on your code. This includes running test LK scripts, Google tests, and manual testing in the user interface.
-
When you are satisfied that there are no errors in your code and that it passes all tests, make a pull request.
-
Make any changes to the code as requested by your code reviewer(s).
-
When your pull request has been approved by the reviewer(s), merge your branch into
developand delete your working branch.
- Download GitHub for Windows: https://desktop.github.com/
- Login with your GitHub info
- Clone exisiting repositories from github.com, or add previously downloaded repos into the client.
- View changes in files, choose which files to commit, and commit.
- Sync with the remote db, which pulls and pushes in one step.
- Download git: https://git-scm.com/ and run the installer with the default components selected and just step through the installation. This means you don't need to change any of the options or selections.
- Full reference available: https://git-scm.com/book/en/v2
- This mini tutorial is developed from http://rypress.com/tutorials/git/
Open the git bash and type:
git config --global user.name "Your Name"
git config --global user.email [email protected]
To get started with an existing repository, navigate within the git bash to the folder you want to check out to, e.g:
cd /c/projects/
On GitHub.com, navigate to the main page of the repository, and under the repository name, click Clone or download. In the Clone with HTTPs section, click to copy the clone URL for the repo. Then execute the clone command within Git Bash by pasting the URL you copied after the git clone command, i.e:
git clone https://github.com/nickdiorio/my-git-repo.git
Before you start working on your files for the day, you will want to pull down changes that other people have committed. You don't have to, but you will be required to before being allowed to push your changes to the remote repo:
git pull
As you add and modify files within your project, you can see the status of your repo at any time:
git status
This will tell you which files have been modified, and which files are new and not being tracked. If you want to remove a file from version control, you type:
git rm file_name
For new files you create, you need to tell Git that you want to explicitly add them to version control. The staging area is basically a place where you stage files before committing them. It guarantees that you commit only exactly the files that you want in a particular commit.
git add orange.html
After you've added all the files you want to add to a particular commit, you commit them with a helpful message about what the commit contains. Commits should contain logical partitions of work that make is easy to look at the log and understand what each commit was for.
git commit -m "Adding a webpage about the color orange"
So, you've staged files, and committed them. But now, you've finally got to push them out to remote repo so that everyone else working on the repo knows about your work and can ingest it into their own working copy. To do this requires write access on the repo you are trying to push to, and you may be prompted for your username and password for GitHub.
git push
To view a history of the repository, you can type any of the following. The second command condenses the log messages to one line, which is helpful for viewing a quick summary. You can also do it for a specific file, as the third line demonstrates.
git log
git log --oneline
git log --oneline orange.html
This log will show the author of each commit, the date, and commit message, plus a unique hashid that identifies the commit.
Git is designed to never loses version history, so to revert a change, git will modify the files in question back to their previous state, and then recommits them as a new commit. The process to do so is fairly simple. Use git log to obtain the id of the commit you want to undo, and then revert it:
git log --oneline
git revert 3e14adc
git push
If you've been developing, but haven't committed and want to undo your changes, the process is a little different since there is no commit id to use. Note, you should be careful using these commands as they operate on the working directory, not on committed snapshots. They permanently undo changes, so make sure that's what you want. Otherwise, you could simply commit what you have and then do a git revert to preserve the history.
git reset --hard
This changes all tracked changes to match the most recent commit.
git clean -f
This removes all untracked files.
A branch is an independent line of development. Branches lend themselves to several standardized workflows for collaborative development, which will be emphasized for SAM. To list existing branches for your project:
git branch
This will display branches for the project. If there is only one branch, it will be called master. This is Git's default branch. The branch with an asterik next to it is the one currently checked out (only one can be checked out at a time).
To create a new branch to work from, and then switch to work from it, simply type:
git branch new_branch_name
git checkout new_branch_name
Now, any changes you make and commit will be isolated from those in the master branch.
Once you've made isolated changes in a branch and tested, and are confident the changes belong in the master branch, you can merge. The merge command always merges into the currently checked out branch.
git checkout master
git merge new_branch_name
Which merges new_branch_name into master
To delete a branch that is no longer needed is straightforward. Git will warn you if you are deleting an unmerged branch.
git branch -d new_branch_name
Modified from: http://nvie.com/posts/a-successful-git-branching-model/