How to Upload Files to Git From Termina;

Nosotros've written earlier how everything we practise is open from day one. I of the means we practice that is past building all of our products—from our blog and our dashboard to a new website for the Peace Corps' Let Girls Larn Initiative—using GitHub. Nosotros do this so that the public can meet the lawmaking nosotros're working on, offer feedback, and copy or fork that lawmaking for their own projects. If you've never used GitHub earlier, information technology tin exist a little intimidating, so we'd like to share the tutorial our own new employees use when they beginning with 18F.

We rent people from many different backgrounds and each new employee brings a different level of comfort with the specific tools we apply on our various projects. The team that runs the 18F website recently started writing downwards the tools and processes that we employ to update the blog and the code that runs the site.

Because some of the people we hire accept never used these tools before, this guide assumes you have no prior knowledge of them either. Nosotros're going to introduce you lot to GitHub, the control line (also called Terminal on OS X), and Markdown through a guided practise. Today you'll learn how to make a web log mail service on the 18F blog.

Every pace volition exist illustrated with a helpful screenshot or blithe GIF that shows you exactly what your screen should look like. We'll go through each pace in gild. At the stop of this postal service, you will know how to:

1. Turn Your Mac Into a Web Development Machine
2. Go Started With GitHub and the Terminal
3. Clone a Repo on Your Computer
4. Build the 18F Site
5. Create a Branch
6. Edit and Commit a Blog Mail service
7. Add Front Matter
8. Learn How to Make a Pull Asking

It is worth noting: In that location are many different ways to do each of these steps. For example, there are apps for using Git like GitHub for Mac and Windows, or Belfry; dozens of different text editors; and competitors to GitHub similar Bitbucket, or SourceForge. You might explore those on your own. This post is a tutorial meant to set up people to work with 18F's Website team.

If y'all have an culling manner of doing any of these steps — or have means to make this more efficient — please let us know past posting an issue here. (You don't have to know how to lawmaking to post an upshot, but you exercise need a GitHub account.)

What you need to go started: a GitHub account and Mac OS Ten. These instructions are primarily for Macs, merely nigh of the instructions will piece of work the same on a Linux calculator. If yous are working on Windows, we suggest checking out this comment that was posted to GitHub that details how to make these instructions work for Windows machines.

Turn your Mac into a web development auto

Using Linux? You can skip this section.

Our colleague Moncef Belyamani wrote a script which turns your Mac into a web evolution machine in well-nigh 15 minutes. Yous will be asked to enter your estimator'due south password three different times during the installation. The terminal doesn't provide whatsoever feedback when you type in your countersign. Just blazon information technology in and press enter.

If yous'd rather not utilise the script, y'all tin can also follow the detailed instructions he wrote on his website. Or follow along with this video he prepared with step by stride instructions to turn your Mac into a web evolution automobile. To use the script, follow the instructions in text beneath:

• Activate terminal by pressing command + space and and so typing "Terminal" in the search field.

The terminal icon looks like this:

And you should have a window like this when you lot open information technology:

• Go to Terminal and paste the post-obit curl --remote-name https://raw.githubusercontent.com/18F/laptop/main/mac and press enter.

• Then paste fustigate mac 2>&1 | tee ~/laptop.log && source ~/.rvm/scripts/rvm and printing enter. This sets up all of the software you lot need in gild to manage the languages we apply at 18F. (For a total listing of programs, click hither).

Getting started With GitHub and the Terminal

Terminal is a program that lets yous transport commands to your computer, and the text you pasted to a higher place is an example of how those commands piece of work. In this guide, whenever you lot see text that looks similar this, you're reading a command. Type the commands exactly as you see them hither (or re-create and paste them into your Concluding) and always press return at the end.

Y'all're going to see the word "directory" a lot in this tutorial. Directory is another word for binder. Directories are specific locations for files on your computer, and the Concluding e'er takes commands starting from a directory. If we say we are "working in a directory" it ways the terminal is starting from that location. Allow's play around with directories a bit:

1. Type ls: this will show you lot everything in the directory where you are currently located. If you type ls -1 it will list them all in a single column for you lot. ls stands for "50isoutht" and the -1 tells your computer to listing the directory in ane cavalcade. If you are in your home directory, you lot will probably see a list in Terminal similar to this screenshot:

1. Now type cd Documents: this will accept you lot into your Documents directory, if that was one of the options shown when you used the 'ls' control higher up. cd stands for "change directory."
2. Type ls -i again to see all the files inside your Documents directory.
3. Type ls -1F: notice a deviation? Any particular in the listing with a / at the end is some other directory.
4. Type cd .. to become back 1 directory. Directories stack on acme of one another and the directory "in a higher place" your current directory is always called ..
5. Type pwd: this command shows you the directory you are currently working in. pwd stands for "print westwardorking directory." You should see something that starts with /Users/, followed past your computer username. This is called your domicile directory and you can always become here past typing cd ~.

I similar to put all my GitHub projects in the same directory. So the first thing I practice is create a directory chosen "code":

1. cd ~ to make sure you lot're in your home directory
2. mkdir code: to create the directory chosen lawmaking in your home directory. mkdir stands for Thouagrande directory.
3. cd code should bring your final into your lawmaking directory.

Pro tip: You tin always get back to your code directory past typing cd ~/code

Clone a repo on your computer

• First, yous want to log into GitHub. Become to https://github.com/login and sign in with your username and password.

At present we can start working with the website. GitHub is a arrangement that stores files and records changes made to them using a piece of software chosen Git, which allows multiple people to make separate changes to a program at the aforementioned time without getting in each others' way. If our plan was a five paragraph essay, Git allows Corey to edit the introduction on one calculator while Jesse edits the determination somewhere else. When both are done, they can move their edits into i copy while preserving the changes from each person.

If you've ever used "Track Changes" in word processing (where edits are highlighted to be approved or rejected), Git is similar that, but with many more features. In software development, Git and other version command tools are helpful when looking for the origin of a bug. Allow'southward say that some code isn't working, but 15 people made edits to it in the final week and you aren't sure where the bug is. With Git, y'all can load an old version of a plan, test for the outcome, then "jump frontwards" through people'southward edits until y'all discover the start one that as well has the problem. That tells you the specific edit to search for the error.

GitHub is a website that shows information from Git. For example, this link shows a spelling edit to this postal service by Melody. Information technology also allows easy discussion about proposed changes, or for people who don't have edit access to write-up problems they run into as "issues." Hither is an issue thread that we made specifically for comments on this post!

In this department you'll see the words "clone," "repository," and its shortened class, "repo." Every project on GitHub is called a "repository" or a "repo;" you lot can come across 18F's listing of repos at this link. A repo contains the entire history of the projection with pointers chosen "commits" represented by "SHAs" that point when and where every file was inverse, and how exactly it inverse. When you "clone" a repo, you download the entire projection plus its history to your estimator. Once you accept a project cloned, you tin make changes on your figurer without affecting the projection as it exists on GitHub.

In this step we are going to clone the 18f.gsa.gov project to your computer.

• Blazon in cd ~/code and press enter to get to the code directory we created before.

• Go to 18f.gsa.gov's GitHub folio and look on the correct side of the page, under the links for "Bug" and "Graphs." You'll meet it says "You tin can clone with HTTPS, SSH, or Subversion." Click on the SSH link and copy the URL (web address) that's in that text box to your clipboard.

If y'all are not on the 18F team only following these directions, you will need to "fork" this repo in order to follow the residual of the steps below. You tin fork this repo past visiting: https://github.com/18F/18f.gsa.gov/fork/. Then, use the SSH link for your fork instead of the one higher up. GitHub's documentation has more data almost forks and how to use them.

• Blazon in git clone and then paste the URL that you copied to your clipboard. This is now copying the 18f.gsa.gov repo to your local computer.

If you see an fault here and have run the Laptop script, you lot demand to open and register your GitHub desktop application. The script installs the application, but the application will not auto-generate an SSH primal until y'all log-in with your 18F GitHub business relationship credentials. Just open GitHub desktop and it volition guide you as a beginning time user. You'll validate your local figurer with 2FA and and then bank check a few more than boxes. Later completing that, re-endeavor the git clone [url] control.

If you run into an error hither and you haven't used the Laptop script mentioned above, yous need to create what's called an SSH key. Yous tin can follow the instructions that are located here. (Pro Tip: You type in everything except the $.) You lot only accept to do this in one case. An SSH key is a pocket-sized file that sits on your computer and tells GitHub who you are. Information technology's kind of like a password your computer types in for y'all automatically. Every time you use this computer to clone a projection or pull/push a project, this SSH fundamental will go used. You will have to do this on every reckoner you accept. Then, if you plan to piece of work on these projects on a separate reckoner, you will need to do this process again.

Branching and pull requests

Let's go back to the 18f.gsa.gov repo from your web browser.

On this folio you lot will see a list of files and folders in this project. All of the web log posts are in a folder called _posts. All of the pages are in a directory called _pages. There's a readme that explains to anyone browsing 18F's 18f.gsa.gov GitHub repo how some of this works. At the height of that window, y'all tin can see a dropdown that says "branch: staging."

Yous are seeing on the website is some other view of files and folders every bit shown here:

If you click on the branch:staging push button, you lot can run into a list of all of the "branches" that exist on this project. Every time you come directly to 18f.gsa.gov, information technology will show you the staging branch because nosotros've made that branch the default.

Branches are petty sandboxes for other people working on the project to gear up contributions without interfering with the master project. When you're finished prepping, you event something called a "pull request" from your co-operative to another. Usually we outcome pull requests to the default branch. This opens a conversation about your contribution and if the team decides it'due south okay, we volition "merge" the pull request and include your piece of work. The default branch on 18f.gsa.gov is "staging." In other projects, you might see information technology called "master."

In the next stride we're going to create a branch, and later on, when you make a pull asking, GitHub will automatically assume you're trying to contribute to the staging co-operative.

On the right side, you lot tin as well see a listing of the existing pull requests and issues. All of the pull requests go to the staging co-operative. When we merge the pull request to the staging branch, GitHub automatically brings those changes into the project, but does not make them live on https://18f.gsa.gov yet.

In Last, enter the following commands:

• cd 18f.gsa.gov to modify directories to 18f.gsa.gov.
• ls -1F to come across all of the files and folders in the GitHub repo, just as you lot saw them on GitHub
• git condition

This last command will bear witness you a little bit of information about what you lot're working on right now. Let's have this autonomously line by line:

• "On branch staging" tells you what co-operative you are currently working on (remember information technology'south staging past default). If you lot made any changes and commited them, y'all'd commit them to the staging branch.
• "Your co-operative is up-to-engagement with 'origin/staging'" means your branch is up to engagement with the staging branch of the remote location called "origin." A Git repo can have whatever number of remote locations it can interact with, chosen "remotes". By default, when yous clone a GitHub repo, a remote chosen "origin" is created that points to the repo on the GitHub website. To view your repo's remote names and their location, type git remote -v. The name "origin" is capricious. Y'all could rename information technology to "github" if you wanted to, but we won't do that now.
• "Nothing to commit / working directory clean" means you're completely up to date and oasis't made whatever changes.

Build the 18F site

Permit's get ahead and get you ready to build the site.

• Yous can practice that by typing ./go init.

This command runs a bunch of commands in the background that you don't need to worry well-nigh. It's downloading and installing a few things called "gems." Gems are trivial bundles of programs written in the Ruby programming language that do really specific things. Jekyll is a gem nosotros employ to create the 18f.gsa.gov website, and our version of information technology needs to employ a few other gems to run and brand the site work. The last thing it does is build the site out for you. Y'all should only need to do this once.

"Building" the site is a procedure where Jekyll takes all the information in the 18f.gsa.gov directory and creates webpages in a directory chosen _site. If you lot want to just build the site, type ./go build.

• To see what the site looks like, you can type ./become serve.

This command "builds" the site and gives yous an address where you can visit information technology to see any changes you fabricated. It should be 127.0.0.one:4000, or http://localhost:4000 for short. You lot can re-create and paste that directly into a browser to double-check. To stop the server, press CTRL + C. If you try to visit http://localhost:4000 after pressing CTRL + C, you won't see anything.

Congratulations! A lot of the steps that you lot've merely done are one time steps. You only have to run the laptop script once. You simply have to clone the repo once. And you just need to run ./become init once. Merely wanted to go on your morale high. Onward!

Create a co-operative

Okay. At present y'all're ready to start editing.

• Open a text editor suitable for web evolution. Nosotros use Sublime Text three, just there are other options like Atom or vim, only we practise not recommend TextEdit or a word processor.

• Now click File -> Open in the menu bar and detect your copy of 18f.gsa.gov, which is located in the directory user/code where user is your username.

• Click on 18f.gsa.gov and click "open."

Voila! You lot tin now come across all of the files that make upward the site. It should await similar this.

We at present want to create a branch, or a sandbox where you lot can make changes to the website. On this team nosotros always work on branches. This allows you to collaborate with teammates without interfering with other people'due south existing work.

• To create a new co-operative, type git checkout -b your-branch-proper noun (The proper name of the co-operative can be anything but it should be descriptive.)

The command git checkout tells git to work on a different co-operative. The -b <branch-name> tells it to create the branch if it does not be however. You lot can switch branches past typing git checkout branch-name. Try switching back and along betwixt the branch you just created and staging to run across how this works.

• Type git status to brand sure y'all're now on the co-operative. Yous should see something that looks like this:

Edit and commit a blog mail

Nosotros're now going to walk you through creating a new blog post for 18f.gsa.gov.

• Blazon ls -1F to come across a list of files and folders that make upwardly 18f.gsa.gov'southward repo.

• Go dorsum to Sublime Text and write your post. Then save your mail in the _posts directory with the name 2015-02-23-new_post.md where '2015-02-23' is today'due south date.

Adding forepart matter

The next step is to add what'southward called front thing. This is metadata for the blog post: actress information Jekyll uses to build parts of the website. It includes things similar the title, authors, description, and date. You add together forepart thing by pasting in the following fields starting on line one of your text editor:

                          ---              title              :              "              How                                          the                                          18F                                          website                                          squad                                          uses                                          GitHub:                                          a                                          tutorial"              layout              :              post              writer              :              -              tune              -              boone              tags              :              -              GitHub              -              Tutorial              -              How We Work              excerpt              :              "              This                                          is                                          a                                          guide                                          that                                          assumes                                          you                                          have                                          no                                          prior                                          knowledge                                          of                                          GitHub                                          or                                          the                                          command                                          line.                                          We're                                          going                                          to                                          introduce                                          y'all                                          to                                          both                                          GitHub                                          and                                          using                                          the                                          control                                          line                                          through                                          a                                          guided                                          exercise.                                          Today                                          you'll                                          learn                                          how                                          to                                          make                                          a                                          blog                                          post                                          on                                          the                                          18F                                          blog."              description              :              "              This                                          is                                          a                                          guide                                          that                                          assumes                                          you lot                                          have                                          no                                          prior                                          knowledge                                          of                                          GitHub                                          or                                          the                                          command                                          line.                                          We're                                          going                                          to                                          innovate                                          yous                                          to                                          both                                          GitHub                                          and                                          using                                          the                                          command                                          line                                          through                                          a                                          guided                                          practice.                                          Today                                          yous'll                                          learn                                          how                                          to                                          brand                                          a                                          blog                                          post                                          on                                          the                                          18F                                          blog."              paradigm              :              /avails/weblog/how-to-github/image.jpg              ---                      

A complete explanation for the front-matter can be found on the 18F Blogging Guide. And now you can offset writing the text of your blog post on line xvi. Say how-do-you-do! It should look like this:

• When y'all are done writing, relieve the post by pressing Command + S.

• And so render back to Terminal.

(Don't worry. You are almost done.)

Learn how to make a pull asking

• Blazon git status again.

You'll notice that git status shows a new section for "untracked files" followed by the name of your blog postal service. Git has four stages that a file can be in: untracked, modified, staged, and committed. Untracked means git doesn't know annihilation about it and volition not lookout man for your changes. Your post is currently untracked and we're about to move the file through all iv stages until information technology is "committed".

• Blazon in git add _posts/2015-02-23-new-postal service.md and hit enter. Make sure to blazon in your bodily filename if it has a different date.

This moves the file from untracked to staged. You simply told git to remember the changes you made to this file. If you make more than changes, the file volition be "modified" and you will need to run that command once again.

• Type git status over again.

You'll see that the file is now listed nether changes to be committed.

Well done! At this point, yous've told Git that this file should be committed, simply you haven't committed annihilation. And then you could piece of work on other things that need to exist committed, or you could commit this file right at present. We're going to commit right now.

• Type git commit -one thousand "My First Mail" followed by enter

Y'all will see something that looks similar this

            [melody-kramer-post 0b22894] My First Post 1 file changed, seven insertions (+) create mode 100644 _posts/2015-02-23-new-post.md                      

That means one file changed — and it was your blog postal service! Congrats, you've officially committed the file! Yous're still at the point where but you tin can see this file, just information technology'south now officially been recorded. You lot've recorded the change for yourself and you're ready to suggest the change to 18F!

• Blazon in git condition one more time.

You lot should see nothing to commit, working directory make clean. That'south because nothing has changed since the last commit.

Note, the following part will piece of work a little differently if you're not an 18F team fellow member and are working from a fork. We are including them here so you can see what happens when we button the file up to GitHub. The instructions, as they are written here, will work for whatever repo you own or any of your forks.

• Type git push origin <co-operative> (where <branch> is the name you gave your branch) and and so hit enter.

This uploads your co-operative and changes to the 18f.gsa.gov projection on GitHub.

• Now, go back to 18F on GitHub and y'all should see that yous recently pushed a co-operative.

It will look similar this:

• Click Compare and Pull Request. It'due south a big green button.

You can add together a trivial comment similar "I wrote a blog postal service. Isn't this the greatest thing?"

• Then click Create Pull Request.

This asks 18F to accept your contribution.

You ever want to make sure what's on your local machine is every bit upwardly to date as it tin can exist. And then whenever yous render to the final, make the following a habit:

• Type git checkout staging followed by git pull again, to make sure your version of the staging branch is electric current.

After you type git pull ane of two things might happen:

1. It will either say "It'south already to upwardly date"
2. Or it will start pulling files which keeps your computer up to date. Your figurer is downloading merely the changes between your computer and GitHub.

Whenever you run git pull you lot ask GitHub to download the most recent changes. If you get the offset message information technology means nothing has changed since the last time you worked on it. If you get the second, it ways someone from the 18F team merged another pull asking.

Once you are all up to date, always remember to create a new branch before making any new changes.

If you lot'd like to make updates to this guide or suggest changes, please add to this issue and nosotros'll cheque information technology out. Thanks!

Moncef Belyamani contributed significantly to this post, helping us shape it and notice our mistakes.

mankemorne1937.blogspot.com

Source: https://18f.gsa.gov/2015/03/03/how-to-use-github-and-the-terminal-a-guide/

Share this post