Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
How we Git
When contributing to 18f.gsa.gov, we typically work on branches off of the main repo, not forks. What does this mean?
If you work for 18F
Making your first changes
Navigate to the
codedirectory you created in the GitHub tutorial by running
Clone 18f.gsa.gov over ssh by running:
git clone email@example.com:18F/18f.gsa.gov.gitwhile in your code directory. This will download the entire 18f.gsa.gov project.
If you're using a mac, run:
git config --global core.editor /usr/bin/vim
Make a new branch by running
git checkout -b your-new-branch
Flip over to your text editor (Sublime Text) and open the document you wish to edit.
Make your changes!
When you're finished editing, flip back to Terminal and run:
git statusyou should see a screen that looks something like this:
On branch your-new-branch Your branch is up-to-date with 'origin/your-new-branch'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: _posts/2015-04-25-my-new-post.md no changes added to commit (use "git add" and/or "git commit -a")
The line that starts "modified" in the middle should be the path to the file you edited.
Add it to your commit by running:
git add _posts/2015-04-25-my-new-post.md
To complete the commit, run:
Now you're in an application called
vim, a text editor kind of like Sublime, but it only works from the command line. You might notice you can't type much in vim, and there's no obvious way to get out of it. Here are some quick tips. Learn more by playing the Zelda-meets-text-editing game Vim Adventures or by reading this in-depth guide.
If you don't want to use
vimyou can use Sublime or Atom or your favorite text editor by following these instructions in the GitHub Help pages.
Ito enter "insert mode" and then write your commit message. This should be a detailed and descriptive message about what you are changing.
escto get out of insert mode.
:wqto save and quit.
After you commit you should see a message like this in the terminal:
[your-branch b8f13be] the first line of your commit message 1 file changed, xxx insertions(+), yy deletions(-)
you did it! You committed your changes. Now they are saved for all of history.
Push your changes back to GitHub by running:
git push --set-upstream origin your-branch. The
--set-upstreampart will tell git to remember to always push
your-branchto GitHub's (
origin) copy of
your-branch. You only need to do this one time per branch.
After your first commit:
You only need to clone 18f.gsa.gov once. When you return to edit a future post, your workflow will look like this:
- Open terminal
git checkout -b your-new-branch
- Open and edit your file in Sublime Text. Save it.
git add path/to/file.extn(if you're not sure of the path, run
git push origin your-new-branch
(If you are unsure if you have run a command correctly, use
git status to check your work.)
When you are finished editing
After you push your changes, go to https://github.com/18f/18f.gsa.gov and click on "Branches" you should find your branch in the list, you might even see a button to create a pull request.
When you are finished editing (or whenever you're ready for feedback from others) go to https://github.com/18f/18f.gsa.gov/pull/new, click the "compare" button.
On this screen you should see two dropdown buttons, one that reads "base: master" and another that reads "compare: master". Base is the name of the branch you want your changes to go to and compare is the name of the branch where your changes are. To submit your changes, click "compare" and choose your branch.
Notify the appropriate authors and the #blog channel about your changes and request that someone else complete the merge. You can also notify the entire blog team by writing @18F/blog.
If you don't work for 18F
If you don't work for 18F, you'll follow the same basic instructions as before but you'll need to fork the repo first.
Go to your fork and clone it to your local machine.
Now you can follow the normal flow above except when you make a pull request you'll want to be sure to click the link that says "compare across forks" and choose your fork and branch.