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?

1. If you work for 18F
2. After your first commit
3. When you are finished editing
4. If you don't work for 18F

If you work for 18F

Making your first changes

First, make sure you run through the GitHub tutorial. (If you get any errors with the laptop script, submit them as issues: to https://github.com/18F/laptop/issues)

1. Open Terminal

2. Navigate to the code directory you created in the GitHub tutorial by running cd ~/code

3. Clone 18f.gsa.gov over ssh by running: git clone git@github.com:18F/18f.gsa.gov.git while in your code directory. This will download the entire 18f.gsa.gov project.

4. If you're using a mac, run: git config --global core.editor /usr/bin/vim

5. Make a new branch by running git checkout -b your-new-branch

6. Flip over to your text editor (Sublime Text) and open the document you wish to edit.

7. Make your changes!

8. When you're finished editing, flip back to Terminal and run: git status you 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.

9. Add it to your commit by running: git add _posts/2015-04-25-my-new-post.md

10. To complete the commit, run: git commit

    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 vim

    • You can use Sublime or Atom or your favorite text editor by following these instructions in the GitHub Help pages.

    OR

    • You can add your commit message in one line! Just run git commit -m 'Created my new post' and your commit is complete. No need for VIM or you go to text editor.

    Type I to enter "insert mode" and then write your commit message. This should be a detailed and descriptive message about what you are changing.

    Press esc to get out of insert mode.

    Type :wq to 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.

11. Push your changes back to GitHub by running: git push --set-upstream origin your-branch. The --set-upstream part will tell git to remember to always push your-branch to 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:

1. Open terminal
2. cd ~/code
3. cd 18f.gsa.gov
4. git checkout -b your-new-branch
5. Open and edit your file in Sublime Text. Save it.
6. git add path/to/file.extn (if you're not sure of the path, run git status)
7. git commit
8. git push origin your-new-branch

(If you are unsure if you have run a command correctly, use git status to check your work.)

You're done!

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.

1. Click here to fork the repo After you fork, you'll have your own copy on GitHub at a url like: https://github.com/`your-username`/18f.gsa.gov

2. 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.