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

(First, make sure you have the laptop script installed) If you get any errors, submit them as issues: to https://github.com/18F/laptop/issues

1. In the Finder, create a folder called "code"

2. Open Terminal

3. Navigate to your code directory by running cd code

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

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

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

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

8. Make your changes!

9. 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 secret-weapon-post
   Your branch is up-to-date with 'origin/secret-weapon-post'.
   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.

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

11. 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 terminal. 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, and see our "Beginner's guide to vim for more information.

    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.

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

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

You're done! If you 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

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: staging" and another that reads "compare: staging". 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/channel in slack about your changes and request that someone else complete the merge.