GitHub Gist: instantly share code, notes, and snippets. GitHub Desktop has no graphical view of commits, which makes it a non-starter for me. I use SourceTree to view history and compare commits to each other or to the current state of the working copy, and the graphical view is indispensable for this. (I use the command line for most other things). Register a new app in GitHub Developer Settings: OAuth Apps. During this process, GitHub will generate a Client ID and Client Secret for your application; make note of these. While setting up your app, use the following settings.
Using GitHub requires more than just committing a README file, but these basics should give you a good grasp on how to interact with the git app and the service. I am using GitHub client on MAC OS X 10.10. (Please note that I am not using GitHub for Enterprise.) I noticed that when there is a merge conflict, GitHub Client is prompting me to either resolve the conflict using Finder or External Editor. I do not see the file in merge conflict within GitHub client itself.
We’ve written before how everything we do is open from day one. One of the ways we do that is by building all of our products—from our blog and our dashboard to a new website for the Peace Corps’ Let Girls Learn Initiative—using GitHub. We do this so that the public can see the code we’re working on, offer feedback, and copy or fork that code for their own projects. If you’ve never used GitHub before, it can be a little intimidating, so we’d like to share the tutorial our own new employees use when they start with 18F.
Report a problem vdot. We hire people from many different backgrounds and each new employee brings a different level of comfort with the specific tools we use on our various projects. The team that runs the 18F website recently started writing down the tools and processes that we use to update the blog and the code that runs the site.
Because some of the people we hire have never used these tools before, this guide assumes you have no prior knowledge of them either. We’re going to introduce you to GitHub, the command line (also called Terminal on OS X), and Markdown through a guided exercise. Today you’ll learn how to make a blog post on the 18F blog.
Every step will be illustrated with a helpful screenshot or animated GIF that shows you exactly what your screen should look like. We’ll go through each step in order. At the end of this post, you will know how to:
It is worth noting: There 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 Tower; dozens of different text editors; and competitors to GitHub like Bitbucket, or SourceForge. You might explore those on your own. This post is a tutorial meant to prepare people to work with 18F’s Website team.
If you have an alternative way of doing any of these steps — or have ways to make this more efficient — please let us know by posting an issue here. (You don’t have to know how to code to post an issue, but you do need a GitHub account.)
What you need to get started:a GitHub account and Mac OS X. These instructions are primarily for Macs, but most of the instructions will work the same on a Linux computer. If you 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 machine
Using Linux? You can skip this section.
Our colleague Moncef Belyamani wrote a script which turns your Mac into a web development machine in about 15 minutes. You will be asked to enter your computer’s password three different times during the installation. The terminal doesn’t provide any feedback when you type in your password. Just type it in and press
enter.
If you’d rather not use the script, you can also follow the detailed instructions he wrote on his website. Or follow along with this video he prepared with step by step instructions to turn your Mac into a web development machine. To use the script, follow the instructions in text below:
The terminal icon looks like this:
And you should have a window like this when you open it:
Getting started With GitHub and the Terminal
Terminal is a program that lets you send commands to your computer, and the text you pasted above is an example of how those commands work. In this guide, whenever you see text that looks like
this , you’re reading a command. Type the commands exactly as you see them here (or copy and paste them into your Terminal) and always press return at the end.
You’re going to see the word “directory” a lot in this tutorial. Directory is another word for folder. Directories are specific locations for files on your computer, and the Terminal always takes commands starting from a directory. If we say we are “working in a directory” it means the terminal is starting from that location. Let’s play around with directories a bit:
I like to put all my GitHub projects in the same directory. So the first thing I do is create a directory called “code”:
Pro tip: You can always get back to your code directory by typing
cd ~/code
Clone a repo on your computer
Now we can start working with the website. GitHub is a system that stores files and records changes made to them using a piece of software called Git, which allows multiple people to make separate changes to a program at the same time without getting in each others’ way. If our program was a five paragraph essay, Git allows Corey to edit the introduction on one computer while Jesse edits the conclusion somewhere else. When both are done, they can move their edits into one 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 like that, but with many more features. In software development, Git and other version control tools are helpful when looking for the origin of a bug. Let’s say that some code isn’t working, but 15 people made edits to it in the last week and you aren’t sure where the bug is. With Git, you can load an old version of a program, test for the issue, and then “jump forward” through people’s edits until you find the first one that also has the problem. That tells you the specific edit to search for the mistake.
GitHub is a website that shows information from Git. For example, this link shows a spelling edit to this post by Melody. It also allows easy discussion about proposed changes, or for people who don’t have edit access to write-up problems they see as “issues.” Here is an issue thread that we made specifically for comments on this post!
In this section you’ll see the words “clone,” “repository,” and its shortened form, “repo.” Every project on GitHub is called a “repository” or a “repo;” you can see 18F’s list of repos at this link. A repo contains the entire history of the project with pointers called “commits” represented by “SHAs” that indicate when and where every file was changed, and how exactly it changed. When you “clone” a repo, you download the entire project plus its history to your computer. Once you have a project cloned, you can make changes on your computer without affecting the project as it exists on GitHub.
In this step we are going to clone the 18f.gsa.gov project to your computer.
If you are not on the 18F team but following these directions, you will need to “fork” this repo in order to follow the rest of the steps below. You can fork this repo by visiting: https://github.com/18F/18f.gsa.gov/fork/. Then, use the SSH link for your fork instead of the one above. GitHub’s documentation has more information about forks and how to use them.
If you run into an error here and have run the Laptop script, you need to open and register your GitHub desktop application. The script installs the application, but the application will not auto-generate an SSH key until you log-in with your 18F GitHub account credentials. Just open GitHub desktop and it will guide you as a first time user. You’ll validate your local computer with 2FA and then check a few more boxes. After completing that, re-try the
git clone [url] command.
If you run into an error here and you haven’t used the Laptop script mentioned above, you need to create what’s called an SSH key. You can follow the instructions that are located here. (Pro Tip: You type in everything except the
$ .) You only have to do this once. An SSH key is a small file that sits on your computer and tells GitHub who you are. It’s kind of like a password your computer types in for you automatically. Every time you use this computer to clone a project or pull/push a project, this SSH key will get used. You will have to do this on every computer you have. So, if you plan to work on these projects on a separate computer, 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 page you will see a list of files and folders in this project. All of the blog 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 top of that window, you can see a dropdown that says “branch: staging.”
You are seeing on the website is another view of files and folders as shown here:
If you click on the
branch:staging button, you can see a list of all of the “branches” that exist on this project. Every time you come directly to 18f.gsa.gov, it will show you the staging branch because we’ve made that branch the default.
Branches are little sandboxes for other people working on the project to prepare contributions without interfering with the main project. When you’re finished prepping, you issue something called a “pull request” from your branch to another. Usually we issue pull requests to the default branch. This opens a conversation about your contribution and if the team decides it’s okay, we will “merge” the pull request and include your work. The default branch on 18f.gsa.gov is “staging.” In other projects, you might see it called “master.”
In the next step we’re going to create a branch, and later on, when you make a pull request, GitHub will automatically assume you’re trying to contribute to the staging branch.
On the right side, you can also see a list of the existing pull requests and issues. All of the pull requests go to the staging branch. 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 Terminal, enter the following commands:
This last command will show you a little bit of information about what you’re working on right now. Let’s take this apart line by line:
Build the 18F site
Let’s go ahead and get you ready to build the site.
This command runs a bunch of commands in the background that you don’t need to worry about. It’s downloading and installing a few things called “gems.” Gems are little bundles of programs written in the Ruby programming language that do really specific things. Jekyll is a gem we use to create the 18f.gsa.gov website, and our version of it needs to use a few other gems to run and make the site work. The last thing it does is build the site out for you. You should only need to do this once.
“Building” the site is a process where Jekyll takes all the information in the 18f.gsa.gov directory and creates webpages in a directory called
_site . If you want to just build the site, type ./go build .
This command “builds” the site and gives you an address where you can visit it to see any changes you made. It should be
127.0.0.1:4000 , or http://localhost:4000 for short. You can copy 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’ve just done are one time steps. You only have to run the
laptop script once. You only have to clone the repo once. And you only need to run ./go init once. Just wanted to keep your morale high. Onward!
Create a branch
Okay. Now you’re ready to start editing.
Voila! You can now see all of the files that make up the site. It should look like this.
We now want to create a branch, or a sandbox where you can make changes to the website. On this team we always work on branches. This allows you to collaborate with teammates without interfering with other people’s existing work.
The command
git checkout tells git to work on a different branch. The -b <branch-name> tells it to create the branch if it does not exist yet. You can switch branches by typing git checkout branch-name . Try switching back and forth between the branch you just created and staging to see how this works.
Edit and commit a blog post
We’re now going to walk you through creating a new blog post for 18f.gsa.gov.
Adding front matter
The next step is to add what’s called front matter. This is metadata for the blog post: extra information Jekyll uses to build parts of the website. It includes things like the title, authors, description, and date. You add front matter by pasting in the following fields starting on line 1 of your text editor:
A complete explanation for the front-matter can be found on the 18F Blogging Guide. And now you can start writing the text of your blog post on line 16. Say hello! It should look like this:
(Don’t worry. You are almost done.)
Learn how to make a pull request
You’ll notice that
git status shows a new section for “untracked files” followed by the name of your blog post. Git has four stages that a file can be in: untracked, modified, staged, and committed. Untracked means git doesn’t know anything about it and will not watch for your changes. Your post is currently untracked and we’re about to move the file through all four stages until it is “committed”.
This moves the file from untracked to staged. You just told
git to remember the changes you made to this file. If you make more changes, the file will be “modified” and you will need to run that command again.
You’ll see that the file is now listed under changes to be committed.
How to cancel an app update on mac ios. Well done! At this point, you’ve told Git that this file should be committed, but you haven’t committed anything. So you could work on other things that need to be committed, or you could commit this file right now. We’re going to commit right now.
You will see something that looks like this
That means one file changed — and it was your blog post! Congrats, you’ve officially committed the file! You’re still at the point where only you can see this file, but it’s now officially been recorded. You’ve recorded the change for yourself and you’re ready to suggest the change to 18F!
You should see
nothing to commit, working directory clean . That’s because nothing has changed since the last commit.
Note, the following part will work a little differently if you’re not an 18F team member and are working from a fork. We are including them here so you can see what happens when we push the file up to GitHub. The instructions, as they are written here, will work for any repo you own or any of your forks.
This uploads your branch and changes to the 18f.gsa.gov project on GitHub.
How To Use Github Mac
It will look like this:
You can add a little comment like “I wrote a blog post. Isn’t this the greatest thing?”
This asks 18F to accept your contribution.
You always want to make sure what’s on your local machine is as up to date as it can be. So whenever you return to the terminal, make the following a habit:
After you type
git pull one of two things might happen:
How To Use Github On Mac
Whenever you run
git pull you ask GitHub to download the most recent changes. If you get the first message it means nothing has changed since the last time you worked on it. If you get the second, it means someone from the 18F team merged another pull request.
Once you are all up to date, always remember to create a new branch before making any new changes.
If you’d like to make updates to this guide or suggest changes, please add to this issue and we’ll check it out. Thank you!
Moncef Belyamani contributed significantly to this post, helping us shape it and find our mistakes.
App Store Github
Apps on GitHub allow you to automate and improve your workflow. You can build apps to improve your workflow. You can also share or sell apps in GitHub Marketplace. To learn how to list an app on GitHub Marketplace, see 'Getting started with GitHub Marketplace.'
GitHub Apps are the officially recommended way to integrate with GitHub because they offer much more granular permissions to access data, but GitHub supports both OAuth Apps and GitHub Apps. For information on choosing a type of app, see 'About apps' and 'Differences between apps.'
How To Use Github Files
If you are using your app with GitHub Actions and want to modify workflow files, you must authenticate on behalf of the user with an OAuth token that includes the
workflow scope. The user must have admin or write permission to the repository that contains the workflow file. For more information, see 'Understanding scopes for OAuth apps.'
For a walkthrough of the process of building a GitHub App, see 'Building Your First GitHub App.'
Requesting support
For questions, bug reports, and discussions about GitHub Apps, OAuth Apps, and API development, explore the GitHub API Development and Support Forum. The forum is moderated and maintained by GitHub staff, but questions posted to the forum are not guaranteed to receive a reply from GitHub staff.
How To Use Github Code
Consider reaching out to GitHub Support directly using the contact form for:
How To Use Github Mac App Download
Comments are closed.
|
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |