Basic commands for managing repositories with git
and GitHub
- Create an account on GitHub (skip this step if you already have an account)
- Configure your GitHub account to use an SSH key - Instructions
- Make sure your local machine has
git
installed - Instructions - GUIs are available for using
git
locally, but we will stick with command line clients- Windows - Git bash
- Linux/Mac - terminal window
You own a repository at GitHub.com and would like to work on its contents locally.
First clone the repository to your local machine.
git clone [email protected]:username/reponame.git
where username
is your GitHub user name, e.g., mhscott
, and reponame
is the name of the repository, e.g., bestrepoever
.
The clone
command will copy the current contents of the repository to your local machine.
You will see a reponame/
subdirectory created in the directory where you issued the clone
command.
You can check the status of your local repo to find important information like which branch you are on, which tracked files you've modified, which files are not tracked, which files are staged for your next commit, etc.
git status
This will give the status of all directories in your local repo regardless of your current working directory.
Optionally, you can limit the status check to a specific directory, e.g., the current working directory .
git status .
You will often work simultaneously on multiple features of your code. Branches help you stay organized.
You can obtain a list of the current branches in your local repo
git branch
You should see a main
branch and any other branches.
The branch with an asterik, e.g., * main
, is the current working branch.
You can create a new branch to implement a new feature. Give the branch a name you can remember.
git branch new-feature
This command only creates the new branch. Type git branch
and you will see * main
and new-feature
.
A second command is required to switch to the new branch.
git checkout new-feature
Now you are on the new branch, which you can verify with git branch
.
To create a new branch and switch to that new branch with one command, use the -b
option.
git checkout -b fix-element
You can then switch back and forth between branches, e.g., back to main
git checkout main
Committing files to your online GitHub repository requires a few steps.
As frequently as you like, you can commit changes in files to any local branch.
git checkout new-feature
To implement this new feature, you make changes to an existing file and/or added new files.
git status
You can see the differences between your current file and its last committed version on your local repo.
git diff existing-file.cpp
Once you are comfortable with the changes you've made and any new files you've added, you can now "stage", or add, the files for a commit.
git add existing-file.cpp new-file.cpp
Do another git status
and you'll see these files listed as staged for commit.
Now you can commit the files along with a brief message that summarizes the changes you've made.
git commit -m "Adding stiffness calculation for shear deformations"
Important: This only commits the modified/new files to your local repository.
One more command is required to push your commits to your repository at GitHub.com.
git push
You should now see your changes/added files listed at github.com/username/reponame
along with the commit history from your push.
Frequently, you want to contribute code back to an public repository owned by another user or organization, e.g., github.com/OpenSees/OpenSees
.
In this case, a couple extra steps are necessary, after which the commands described above will suit your workflows.
To work with a repository that you do not own, the best approach is to fork the repository into your GitHub account.
- Go to the repository
github.com/username/reponame
and create a fork. - Go to your forked repository
github.com/yourusername/reponame
. - Clone your fork to your local machine (same process shown above).
git clone [email protected]:yourusername/reponame.git
You can now work with the forked repo as if it is your own.
You should keep your fork up to date with the "upstream" repo. This will allow you to get the latest changes made by the owners as well as by other contributors.
git remote add upstream [email protected]:username/reponame.git
git fetch upstream
git pull upstream main
You only have to do git remote add
and git fetch
once. After the first time, git pull upstream main
is all you have to do to get the latest upstream code.
Make upstream updates a regular habit for your forks of active repositories, e.g., if you fork OpenSees, do upstream updates once a week.
To check the addresses of your remote repositories
git remote -v
You should see two remotes: origin
and upstream
.
In some cases, you will work with several upstream repositories, e.g., upstream-1
, upstream-2
, or better names.
To change the URL of remote addresses, e.g., if the owner of the upstream repo changes the repo name
git remote set-url upstream [email protected]:username/newreponame.git
Typically, one does the git pull upstream main
while their local main
is the current branch.
To merge the upstream changes into a local branch, e.g., new-feature
git checkout new-feature
git merge main
Do this merge for every local branch under active development.
Fast forward... you've committed changes from your local repo to your fork and you're ready to share your contributions with the world.
To this end, push a branch from your fork to the upstream repo and make a "pull request".
Change to the branch you'd like to push upstream, then map your branch to your origin repo on GitHub.com.
git checkout new-feature
git push --set-upstream origin new-feature
Note: You only have to do the --set-upstream
once per branch. After that, any pushes to the mapped branch will go straight to your origin repo on GitHub.com.
Now go to your GitHub repo at github.com/yourusername/reponame
.
Click on Contribute
, then Open pull request
.