A safe place to experiment with git & GitHub in a group setting
This is a playground open to anyone looking to practice using git & GitHub in a group project. Feel free to make any and all changes as you test your GitHub chops. One caveat, we ask you please do not change the main readme unless you are making an improvement (P.S. please help the next person and make improvements).
To reiterate this repository is to get people (you!) comfortable with using GitHub - do not be scared to try things out!
- Fork the repo (this step is optional if you have have "contributor" access to the repo).
- Clone from your command line
git clone https://github.com/youruserID/github-playground.git
. - Move to main directory
cd github-playground
- Check your status
git status
Should see "On Branch Master" "Your branch is up-to-date with 'origin/master'" - Create and checkout a branch to work from:
git checkout -b <branch_name>
EX:git checkout -b training-branch
You can see all branches by typinggit branch
. Note: we are using training-branch in this example but by the time you follow these instructions someone may have already createdtraining-branch
you should create a unique branch. - Read about git branching and merging.
- Make a change to an existing file or create a new file and save.
EX: echo "print("hello")" > hello.py
- Check status of your change with
git status
. Your file should show up under "Untracked Files" EX:hello.py
or whatever file you created. - Add file to changes
git add <filename>
orgit add .
(adds all untracked files -- CAREFUL use with caution) EX:git add hello.py
- See exactly what changes are staged
git diff --cached
(orgit diff
if files are not yet staged). - Commit your changes
git commit -m "Hey this is my first commit"
Read about how to write good commit messages. - Check your remote
git remote -v
(if you started by cloning a repo from GitHub origin should already be set) - Push your changes to the remote server by typing
git push <remote-name> <your-branch>
EX:git push origin training-branch
- Open the repo in GitHub and select your branch.
- You should see compare and pull request. This will bring up a summary of your changes and show you what branch you are merging.
- Edit your message and click submit. Now you should see your pull request show up in the pull requests tab!
- In a real project your PR may be discussed and reviewed. Stakeholders may suggest changes or updates and (hopefully) eventually your code will be merged!
- If you need to make changes to the code in your PR you can make the changes EX:
echo "print("hello good sir")" > hello.py
git diff
to check your changesgit add hello.py
to stage your changesgit commit -m "More formal greeting"
- Do another
git push origin <branch>
and changes show automatically show up in the PR (No need to open another PR).
- If you need to make changes to the code in your PR you can make the changes EX:
After your commit has been merged, you may want to maintain your local fork up to date:
- Add the project branch as an upstream repository i.e.
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
- Fetch the master branch from upstream
git fetch upstream
- Checkout your fork's local master branch
git checkout master
- Merge the upstream/master
git merge upstream/master
- At this point you can always delete your local branch that you created (if you no longer need it) i.e.
git branch -d training-branch
- To ensure that your fork on GitHub is also up-to-date you can do
git push origin master
This only scratches the surface of what is possible with git and GitHub. Feel free continue to use this repo when you need to test out (or document for others!) more complicated workflow.
- Use pull requests whenever possible. Direct commits to
master
are best for trivial changes. - Use separate branches for each enhancement or fix you're working on, unless the circumstances dictate otherwise.
- Make your new branch from the most appropriate current branch, e.g. if you’re working on a contribution to
feature-x
, branch from this (and especially notmaster
). - Make sure your branch is up to date before you start working.
- Give branches appropriate names, e.g.
fix/238
(where 238 is the issue number) ororiginal-branch/my-feature
. - Make each PR as concise as possible. Don’t rewrite large sections of the codebase to fit a tiny contribution. Make a separate issue or PR for any extra modifications that need to be made.
- Don't merge new commits from
master
to your branches: wait till the final merge intomaster
(or rebase your branches tomaster
). - Don't be scared and ask for help. Most of us have learned this "on the job".
- Try GitHub desktop client if you prefer to work with GUI
- Created by Code School: TryGit teaches you how to use Git in 15 minutes
- Lifesaving advice from ohshitgit
- Udacity course
- Learn Version Control with Tower (videos)
- Comparing Workflows for learning how the Forking Workflow…works
- Do not worry, we have all been there!
- Join #github-help channel on Slack and ask for help.
- DM someone directly. Below users have volunteered to assist with GitHub questions:
- @mattgawarecki, @bstarling, @john
- Was something not clear or was there an area you struggled with? Submit a Pull request (PR) or open an issue to help us improve!