- Fork the data_access_examples repo on GitHub and clone the new fork to your development environment
git clone github.com/<githubusername>/<repository_name>
-
Make a new branch and make your changes to the source files in the branch
-
Add changed files to the commit ...
git add <list of your changed files> -
... and commit them:
git commit -
Push the accumulated commits to your fork/branch in GitHub:
git push -
Open GitHub and issue a pull request.
-
IMPORTANT Keep your code up-to-date with the upstream repository using the following commands. As commits from other developers accumulate in the upstream main branch, rebase your branch onto those changes prior to issuing a pull request.
git remote add upstream https://github.com/alabamawaterinstitute/data_access_examples.git
git fetch upstream # updates local repository with upstream commits by others
git pull --rebase upstream main # rebases your commits on top of upstream commits
A step-by-step guide illustrating how to fork and clone
a repository can be found
here.
Once a new fork is created, clone it to an empty local directory
of your choice (if the directory does not exist already,
git clone will create it):
# navigate to a local directory where you want to store the repo
cd <local/directory/of/your/choice>
# clone your forked repo
git clone github.com/<githubusername>/data_access_examples.git
Set up your user name and email in your local repo config
git config user.name "Your name as you would like it displayed in the commit"
git config user.email "Your email address"
Alternatively, you can change your machine global git configs:
git config --global user.name "Your name as you would like it displayed in the commit"
git config --global user.email "Your email address"
Your GitHub fork that you just cloned from will be labeled as the origin
remote in your local git repository. If for some reason you are working from another
fork, you can add yours like this:
git remote add origin main https://github.com/<githubusername>/data_access_examples.git
To get the latest updates from the main data_access_examples codebase,
we need to add it as a second remote. It is common to
name this remote, upstream
git remote add upstream https://github.com/alabamawaterinstitute/data_access_examples.git
Later in the process, you will need to push commits back to your fork. Because GitHub imposes security limitations on pushing via https, you will either need to configure a personal token or add an ssh token and change the push url for your remote. This isn't necessary until you make a change and try to push it, but while you are adding the remote, it is convenient to set up.
In order to change the push URL of a Git remote, you can follow the steps below.
- Change to the directory where the repository is located:
```
cd /path/to/repository
```
- Run git remote to list the existing remotes and see their names and URLs:
git remote -v
The output will look something like this:
origin https://github.com/<githubusername>/repo_name.git (fetch)
origin https://github.com/<githubusername>/repo_name.git (push)
- Change your remote's push URL from HTTPS to SSH with the git remote set-url
command. Use the git remote set-url command followed by the remote name, and the remote’s URL:
git remote set-url --push <remote-name> <remote-url>
To change the URL of the origin to [email protected]:user/repo_name.git you would type:
git remote set-url --push origin [email protected]:<githubusername>/data_access_examples.git
-
Now Verify that the remote URL has changed with
git remote -v -
Generate a new SSH key, following instructions here:
ssh-keygen -t ed25519 -C [email protected]
When you're prompted to "Enter a file in which to save the key", you can press Enter to accept the default file location.
- Print out the contents of the public key and copy these for paasing into the GitHub account.
cat <location where the public key was saved in step 2, probably "id_ed25519.pub">
After getting the SSH key, save it in your GitHub account per instructions here
To incorporate any changes from the main codebase into your
local repo main, checkout your main branch and do a
fetch-and-rebase using the pull command.
# checkout the main branch
git checkout main
# fetch and rebase changes
git pull --rebase upstream main
Finally, use the push command so these updates are in the
GitHub main branch on your fork.
# assuming you still have `main` checked out
git push
Branches are parallel versions of the repository that allow you to make changes and tinker as much as you would like without disrupting the main codebase. It is recommended to create a new branch for each bite-sized contribution you make or issue you respond to.
The above fetch-and-rebase-into-main process is superfluous in some ways. By maintaining a connection to the upstream repository, you can always have access to the latest version of the upstream codebase.
If you always make your development branches start from the upstream, it will help make your commits much easier to rebase and merge into the main development branch when you are ready to contribute them.
Here is how to create a new branch:
git fetch upstream
git checkout upstream/main
This will update your local copy of upstream and checkout a 'detached HEAD' version of it. (There will be a message that explains what that means when you do it.)
Then create your development branch from the 'detached HEAD' branch:
git checkout -b <new-branch-name>
The above command will create and checkout the new branch.
Otherwise, the checkout command is used to navigate between
branches. It updates files in your working directory to match
the version stored in that branch.
git checkout <branch-name>
At anytime after you create your development branch, you can synchronize your local commits (there will be nothing to start with; much more later) with you GitHub fork.
To Push the local branch to the remote repository,
git push -u origin <branch-name>
or
git push –set-upstream origin <branch-name>
Any time you update main with changes from the upstream
remote (step 5), it is advised to rebase any local development
branches, too. Rebasing ensures that your changes are based
from what everyone else has already done.
# check out the branch you would like to rebase
git checkout <branch-name>
# rebase the branch
git rebase main
In your local development branches, explore the code, make changes, and experiment at will. Be creative!
git add <list of your changed files>
Commits should be accompanied by a concise and brief comment. Like the "save" button in a word processor, commits should be made early and often. A small commit with a precise comment, is often more useful that a massive commit with a detailed changelist buried in bullets. If additional comments are necessary, these may be included following a blank line as shown below.
git commit -m 'Make Brief comments to explain your Feature
Additional detail below a blank line, like this.
-An explanation of why a change was made can help here
-Bullets are useful for a large commit
-But usually, it is better to just commit more often
-With a short one-line description of each little change'
In order to get any accumulated commits in GitHub on your remote branch, push the changes. Make sure that you have the correct development branch checked out, first.
# make sure the right development branch is checked out. There will be "*" next to the checked out branch
git branch -vv
# if the correct development branch is not checked out, change it
git checkout <branch-name>
# push commits to the development branch
git push origin <branch-name>
After you git push all commits to your branch and you believe you are ready to post code to the main codebase, open GitHub and issue a pull request. (It will probably be a highlighted button at the top of the page -- "New Pull Request"). Of course, please test, document, style check (see 'Black'), and prepare (as-needed) demonstration notebooks, etc. More information about pull requests can be found here. From that page:
"Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch."
A pull request will allow someone else to look at your code with you to make sure that it is ready to share with the world. Most of the time, someone who was involved with preparing the code can be the reviewer; for major changes, it should be someone outside the core development team.
- If some of the terminology used above is confusing - it is confusing to us too, sometimes! This GitHub glossary is a useful reference.
- For a better guide on how to use GitHub to collaborate on NOAA development projects, please see the documentation associated with the DMOD repo
git stashtakes changes and puts them on a stack. See the stashed changes withgit stash listgit show -pshows the changes incorporated in the most recent commit on your active branch -- helpful for figuring out where you are in a not-yet-complete edit.git logshows where you are in the development tree.git log --graph --oneline --alladds a few key options to make things more clear.git rebase --abortlets you back out of a sticky situation.git add -padds changes one-by-one through your repository.git rebase -iallows for a combination of rebasing and cleaning up the commits in your history at the same time. USE WITH CARE. This rewrites your history so it shouldn't be used on any branch where someone else is trying to merge things with you.git commit --amendadjusts the last commit to fix a little bug, a commit message typo, etc. This also rewrites history, so it is better not to use it if someone has already started to work from your messy commit.