How to Use Github and the Terminal: A Guide #542

Closed
melodykramer opened this Issue Feb 19, 2015 · 31 comments

Comments

Projects
None yet
@melodykramer
Contributor

melodykramer commented Feb 19, 2015

The tutorial is available on our blog: https://18f.gsa.gov/2015/03/03/how-to-use-github-and-the-terminal-a-guide/ come back here to discuss how we can improve it!

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 19, 2015

Contributor

Note: Anyone who is not an 18F employee will not be able to push a new branch to this GitHub repository. If you try you will get an error.

Contributor

gboone commented Feb 19, 2015

Note: Anyone who is not an 18F employee will not be able to push a new branch to this GitHub repository. If you try you will get an error.

@seanherron

This comment has been minimized.

Show comment
Hide comment
@seanherron

seanherron Feb 19, 2015

Contributor

This is really fantastic! As a suggestion, maybe add screenshots or inline GIFs of you doing various command line activities? LICEcap is my tool of choice. Then you can do cool things like this:

recorded-screen-as-animate-gif

Contributor

seanherron commented Feb 19, 2015

This is really fantastic! As a suggestion, maybe add screenshots or inline GIFs of you doing various command line activities? LICEcap is my tool of choice. Then you can do cool things like this:

recorded-screen-as-animate-gif

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 19, 2015

Contributor

SO COOL. Will add that. @seanherron. Thanks!

Contributor

melodykramer commented Feb 19, 2015

SO COOL. Will add that. @seanherron. Thanks!

@stvnrlly

This comment has been minimized.

Show comment
Hide comment
@stvnrlly

stvnrlly Feb 19, 2015

Member

I haven't been able to try it yet for inclusion in the Code for DC guide, but Git for Windows supposedly provides an interface with Mac/Linux commands, which would make this guide universally applicable: https://msysgit.github.io/

Member

stvnrlly commented Feb 19, 2015

I haven't been able to try it yet for inclusion in the Code for DC guide, but Git for Windows supposedly provides an interface with Mac/Linux commands, which would make this guide universally applicable: https://msysgit.github.io/

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@stvnrlly

This comment has been minimized.

Show comment
Hide comment
@stvnrlly

stvnrlly Feb 19, 2015

Member

Thanks! I'm going to see what I can "borrow" from this. We also have materials for other stuff you cover here:

Installing Jekyll
Submitting a post

Here are a few small things:

  • I don't believe Homebrew will work on a Linux machine. The package manager would vary from distro to distro, but the instructions should be the same with that manager's command plugged in.
  • I don't see brew actually used here. I had used it to install Git: that appears to be redundant, but I must have had some reason for it...
  • You may want to recommend installing RVM no matter what. Ruby's use of the path for commands can be really confusing if you don't know what's going on, and RVM avoids this. (I see that a lot is happening in the ./go command, so this may be unnecessary)
  • Headers would be nice to break things up and create link points.
  • The YAML front matter example implies that you should type --- on line 1 rather than --- on line 1. It may be clearer to just say "Don't forget the triple dashes."
Member

stvnrlly commented Feb 19, 2015

Thanks! I'm going to see what I can "borrow" from this. We also have materials for other stuff you cover here:

Installing Jekyll
Submitting a post

Here are a few small things:

  • I don't believe Homebrew will work on a Linux machine. The package manager would vary from distro to distro, but the instructions should be the same with that manager's command plugged in.
  • I don't see brew actually used here. I had used it to install Git: that appears to be redundant, but I must have had some reason for it...
  • You may want to recommend installing RVM no matter what. Ruby's use of the path for commands can be really confusing if you don't know what's going on, and RVM avoids this. (I see that a lot is happening in the ./go command, so this may be unnecessary)
  • Headers would be nice to break things up and create link points.
  • The YAML front matter example implies that you should type --- on line 1 rather than --- on line 1. It may be clearer to just say "Don't forget the triple dashes."
@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 19, 2015

Contributor

Thanks for your feedback @stvnrlly!

Answers to a couple specific points:

I don't believe Homebrew will work on a Linux machine.

That's correct. We don't have many Linux users here, and no few windows users so these instructions are "Mac-centric" at the moment. That step is likely (if not definitely) unnecessary on Linux because package managers like apt-get and yum are already available.

I don't see brew actually used here. I had used it to install Git: that appears to be redundant, but I must have had some reason for it...

RVM uses brew (or at least prompts you to install it when you run rvm install 2.2.0). We decided to include it as a separate step for transparency into what all the things are that you're installing on your computer. I also used brew to install git and it's not redundant at all! Using homebrew is useful, if you want to run a version of git other than the one OS X gives you (Apple gives you 2.0.0, I think, brew will let you use the latest, 2.3).

You may want to recommend installing RVM no matter what.

Good plan, especially because everyone is going to have to install it anyway :)

Thanks again for the feedback and advice, it's really helpful!

Contributor

gboone commented Feb 19, 2015

Thanks for your feedback @stvnrlly!

Answers to a couple specific points:

I don't believe Homebrew will work on a Linux machine.

That's correct. We don't have many Linux users here, and no few windows users so these instructions are "Mac-centric" at the moment. That step is likely (if not definitely) unnecessary on Linux because package managers like apt-get and yum are already available.

I don't see brew actually used here. I had used it to install Git: that appears to be redundant, but I must have had some reason for it...

RVM uses brew (or at least prompts you to install it when you run rvm install 2.2.0). We decided to include it as a separate step for transparency into what all the things are that you're installing on your computer. I also used brew to install git and it's not redundant at all! Using homebrew is useful, if you want to run a version of git other than the one OS X gives you (Apple gives you 2.0.0, I think, brew will let you use the latest, 2.3).

You may want to recommend installing RVM no matter what.

Good plan, especially because everyone is going to have to install it anyway :)

Thanks again for the feedback and advice, it's really helpful!

@jiffyclub

This comment has been minimized.

Show comment
Hide comment
@jiffyclub

jiffyclub Feb 23, 2015

One thing to note is that the xcode-select --install command will only work on more recent versions of Mac OS X. I can't remember if that showed up with Mavericks or Mountain Lion. But on older versions of OS X you need to either download and install the "Command Line Tools for Xcode" or install Xcode and install the command line tools from within the Xcode preferences.

msysgit installs a utiltiy called Git Bash that's a lot like the Bash shell you find on Mac/Linux, but it's not a perfect copy (lacks the man command for example, and a simple text editor like nano).

One thing you are missing here is mention of setting your name and email via git config:

git config --global user.name "My Name"
git config --global user.email "email@example.com"

You'll definitely want that done for new users before they start making commits. It's also a good idea to set an editor (git config --global core.editor) so that people don't accidentally find themselves in vim when they forget the -m flag to commit.

(Plug for Software Carpentry's Git lesson and installation instructions.)

One thing to note is that the xcode-select --install command will only work on more recent versions of Mac OS X. I can't remember if that showed up with Mavericks or Mountain Lion. But on older versions of OS X you need to either download and install the "Command Line Tools for Xcode" or install Xcode and install the command line tools from within the Xcode preferences.

msysgit installs a utiltiy called Git Bash that's a lot like the Bash shell you find on Mac/Linux, but it's not a perfect copy (lacks the man command for example, and a simple text editor like nano).

One thing you are missing here is mention of setting your name and email via git config:

git config --global user.name "My Name"
git config --global user.email "email@example.com"

You'll definitely want that done for new users before they start making commits. It's also a good idea to set an editor (git config --global core.editor) so that people don't accidentally find themselves in vim when they forget the -m flag to commit.

(Plug for Software Carpentry's Git lesson and installation instructions.)

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 23, 2015

Contributor

Thanks for the tips, @jiffyclub the git config settings step is definitely among those set-it-and-forget it things I always miss when going through the first round with folks.

I'll have to take a look at msysgit too.

Contributor

gboone commented Feb 23, 2015

Thanks for the tips, @jiffyclub the git config settings step is definitely among those set-it-and-forget it things I always miss when going through the first round with folks.

I'll have to take a look at msysgit too.

@jiffyclub

This comment has been minimized.

Show comment
Hide comment
@jiffyclub

jiffyclub Feb 23, 2015

Another thought: The Xcode tools aren't the only way to get Git onto a Mac. Other options include downloading an installer straight from the Git website and installing GitHub for Mac.

Another thought: The Xcode tools aren't the only way to get Git onto a Mac. Other options include downloading an installer straight from the Git website and installing GitHub for Mac.

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 23, 2015

Contributor

That is true, but I'm pretty sure Xcode tools are required for installing Homebrew (and rvm uses homebrew). That used to be the case, anyway.

Contributor

gboone commented Feb 23, 2015

That is true, but I'm pretty sure Xcode tools are required for installing Homebrew (and rvm uses homebrew). That used to be the case, anyway.

@jiffyclub

This comment has been minimized.

Show comment
Hide comment
@jiffyclub

jiffyclub Feb 23, 2015

Yeah, since you're installing Homebrew it makes sense to start with the Xcode tools.

Yeah, since you're installing Homebrew it makes sense to start with the Xcode tools.

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 24, 2015

Contributor

@seanherron Added screenshots. thanks for the suggestion.

Contributor

melodykramer commented Feb 24, 2015

@seanherron Added screenshots. thanks for the suggestion.

@melodykramer melodykramer changed the title from Refine these instructions that will help people create a blog post using Github through the terminal. to How to Use Github and the Terminal: A Guide Feb 24, 2015

@willharding

This comment has been minimized.

Show comment
Hide comment
@willharding

willharding Feb 24, 2015

Nice job Mel. I have gone through similar process a couple of different times and I wish those places had something like this. Also - animated gifs make this even better!

Nice job Mel. I have gone through similar process a couple of different times and I wish those places had something like this. Also - animated gifs make this even better!

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 24, 2015

Contributor

Thanks @willharding!

Contributor

melodykramer commented Feb 24, 2015

Thanks @willharding!

@afeld

This comment has been minimized.

Show comment
Hide comment
@afeld

afeld Feb 24, 2015

Member

This is great. 🎇 My one little request is to put it somewhere that it can be collaborated on, e.g. a Markdown file in a repository.

Member

afeld commented Feb 24, 2015

This is great. 🎇 My one little request is to put it somewhere that it can be collaborated on, e.g. a Markdown file in a repository.

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 24, 2015

Contributor

@afeld It will go on our blog, I believe next week.

Contributor

melodykramer commented Feb 24, 2015

@afeld It will go on our blog, I believe next week.

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 24, 2015

Contributor

You can now make line edits here: https://github.com/18F/18f.gsa.gov/pull/550/files

Contributor

melodykramer commented Feb 24, 2015

You can now make line edits here: https://github.com/18F/18f.gsa.gov/pull/550/files

@afeld

This comment has been minimized.

Show comment
Hide comment
@afeld

afeld Feb 24, 2015

Member

This may be a separate discussion, but why a blog post, rather than somewhere more "evergreeen" like http://18f.github.io/guides/?

/cc @blacktm @mbland

Member

afeld commented Feb 24, 2015

This may be a separate discussion, but why a blog post, rather than somewhere more "evergreeen" like http://18f.github.io/guides/?

/cc @blacktm @mbland

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 24, 2015

Contributor

Good question, @afeld we're working on a separate, slightly modified version to include in a guide.

Contributor

gboone commented Feb 24, 2015

Good question, @afeld we're working on a separate, slightly modified version to include in a guide.

@monfresh

This comment has been minimized.

Show comment
Hide comment
@monfresh

monfresh Feb 25, 2015

Member

First of all, great work. I'm sure many people will find this helpful. I haven't read through the whole thing yet, but a few things jumped out at me:

  • GitHub is misspelled. The H is capitalized. It's not Github.
  • My understanding of the main purpose of the tutorial is that it should teach someone how to write a blog post on the 18F blog. Therefore, setting up a dev environment should not be one of the main focal points, and should not sound daunting to the newbie. Setting up a Ruby dev environment on a Mac is a lot simpler than how it is portrayed in the article. It can also be automated in a way that all the user has to do is type in one command in the Terminal, and then click a few buttons, and enter their password in Terminal. I would suggest moving the setup portion to a separate article (in some kind of central "Guides" portal, similar to Code for America's howto repo), and make the entire setup be the first thing they do to get it out of the way, as opposed to doing it in disjointed chunks. One such automated tool for setting up a dev environment is Thoughbot's laptop script. I have just finished testing a modified version of the script that I plan to publish soon to make it easy for new 18F hires (or anyone else) to configure their new Mac.
  • When addressing complete beginners, you really have to spell everything out. If you mention a tool like Sublime Text, a link must be provided. Same with phrases like Go to Finder and type in Terminal. Type in Terminal where in Finder? A better suggestion would have been to search for Terminal in Spotlight with instructions for accessing Spotlight via CMD-space or clicking the magnifying glass icon in the top right (with an animated gif). I've written a very detailed and popular article to help people set up a Ruby dev environment, and I tried to be as explicit as possible, with plenty of screenshots. I'm planning on updating it with animated gifs and with a link to my automated script.
  • Not everyone who wants to write a blog post will necessarily want to learn how to use Git from the command line. Even though I have used Git for years, I still prefer to use a GUI like Tower. For the newbie, GitHub for Mac is free and very accessible. I would use that to show how to stage and commit as opposed to the command line.

I love writing guides so I'd be happy to help you make this perfect and fun for the newbie. Perhaps it's my 14 years of QA background, but I find it very helpful to walk through my entire guide to catch any errors. Skimming through this article I've found a few errors where the command that should be run is misspelled, or is not case-sensitive when it should be. It can be extremely frustrating to a newbie to follow incorrect instructions and not know why it's not working. Many will just give up right then and there and might not tell you about the issue.

Member

monfresh commented Feb 25, 2015

First of all, great work. I'm sure many people will find this helpful. I haven't read through the whole thing yet, but a few things jumped out at me:

  • GitHub is misspelled. The H is capitalized. It's not Github.
  • My understanding of the main purpose of the tutorial is that it should teach someone how to write a blog post on the 18F blog. Therefore, setting up a dev environment should not be one of the main focal points, and should not sound daunting to the newbie. Setting up a Ruby dev environment on a Mac is a lot simpler than how it is portrayed in the article. It can also be automated in a way that all the user has to do is type in one command in the Terminal, and then click a few buttons, and enter their password in Terminal. I would suggest moving the setup portion to a separate article (in some kind of central "Guides" portal, similar to Code for America's howto repo), and make the entire setup be the first thing they do to get it out of the way, as opposed to doing it in disjointed chunks. One such automated tool for setting up a dev environment is Thoughbot's laptop script. I have just finished testing a modified version of the script that I plan to publish soon to make it easy for new 18F hires (or anyone else) to configure their new Mac.
  • When addressing complete beginners, you really have to spell everything out. If you mention a tool like Sublime Text, a link must be provided. Same with phrases like Go to Finder and type in Terminal. Type in Terminal where in Finder? A better suggestion would have been to search for Terminal in Spotlight with instructions for accessing Spotlight via CMD-space or clicking the magnifying glass icon in the top right (with an animated gif). I've written a very detailed and popular article to help people set up a Ruby dev environment, and I tried to be as explicit as possible, with plenty of screenshots. I'm planning on updating it with animated gifs and with a link to my automated script.
  • Not everyone who wants to write a blog post will necessarily want to learn how to use Git from the command line. Even though I have used Git for years, I still prefer to use a GUI like Tower. For the newbie, GitHub for Mac is free and very accessible. I would use that to show how to stage and commit as opposed to the command line.

I love writing guides so I'd be happy to help you make this perfect and fun for the newbie. Perhaps it's my 14 years of QA background, but I find it very helpful to walk through my entire guide to catch any errors. Skimming through this article I've found a few errors where the command that should be run is misspelled, or is not case-sensitive when it should be. It can be extremely frustrating to a newbie to follow incorrect instructions and not know why it's not working. Many will just give up right then and there and might not tell you about the issue.

@melodykramer

This comment has been minimized.

Show comment
Hide comment
@melodykramer

melodykramer Feb 25, 2015

Contributor

@monfresh Thanks for the feedback. We're still iterating on this guide, which is why we published it here for suggestions! I wasn't familiar with laptop but am happy to add that once you've finished your testing. And you're right, we still need to add screenshots for certain steps.

We chose to do this with the command line because people have requested it. I will add a part explaining that users can also use a GUI. (Instructions for that are already pretty good on Github.)

Would love to walk through this with you when we're done! Thanks for the feedback. (If you could point out the case sensitive errors you found, that would be really helpful.)

Contributor

melodykramer commented Feb 25, 2015

@monfresh Thanks for the feedback. We're still iterating on this guide, which is why we published it here for suggestions! I wasn't familiar with laptop but am happy to add that once you've finished your testing. And you're right, we still need to add screenshots for certain steps.

We chose to do this with the command line because people have requested it. I will add a part explaining that users can also use a GUI. (Instructions for that are already pretty good on Github.)

Would love to walk through this with you when we're done! Thanks for the feedback. (If you could point out the case sensitive errors you found, that would be really helpful.)

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Feb 25, 2015

Contributor

@monfresh if you are so inclined, you can point out any corrections that need to be made on the post at #550 or push corrections directly to that branch. If not, I've been meaning to take a proofreading pass over the command line elements, too, and will keep an eye out for the kinds of things you're noticing.

We'd love to jam with you on how to better automate and abstract away much of the setup parts of this. We've managed to do a lot of that with the go script in the repo, but right now running that requires a ruby environment. It'd be great if we could make getting the local environment ready as simple as cloning the repo and running a script. Most of us are real Ruby n00bs and this is a reflection of what we've learned on the fly; we're definitely interested in areas where there's room for improvement.

Contributor

gboone commented Feb 25, 2015

@monfresh if you are so inclined, you can point out any corrections that need to be made on the post at #550 or push corrections directly to that branch. If not, I've been meaning to take a proofreading pass over the command line elements, too, and will keep an eye out for the kinds of things you're noticing.

We'd love to jam with you on how to better automate and abstract away much of the setup parts of this. We've managed to do a lot of that with the go script in the repo, but right now running that requires a ruby environment. It'd be great if we could make getting the local environment ready as simple as cloning the repo and running a script. Most of us are real Ruby n00bs and this is a reflection of what we've learned on the fly; we're definitely interested in areas where there's room for improvement.

@monfresh

This comment has been minimized.

Show comment
Hide comment
@monfresh

monfresh Feb 25, 2015

Member

@gboone Will do. I have a spare laptop that I use just for these purposes. I will wipe it clean, install Yosemite, and go through the guide step by step and make corrections as I find them.

Member

monfresh commented Feb 25, 2015

@gboone Will do. I have a spare laptop that I use just for these purposes. I will wipe it clean, install Yosemite, and go through the guide step by step and make corrections as I find them.

@macloo

This comment has been minimized.

Show comment
Hide comment
@macloo

macloo Mar 4, 2015

I wrote a document covering GitHub for Windows (the app) over the summer:

http://bit.ly/mmgitwin

Not an issue per se, but feel free to use it or take parts of it, if it helps.

macloo commented Mar 4, 2015

I wrote a document covering GitHub for Windows (the app) over the summer:

http://bit.ly/mmgitwin

Not an issue per se, but feel free to use it or take parts of it, if it helps.

@gboone

This comment has been minimized.

Show comment
Hide comment
@gboone

gboone Mar 5, 2015

Contributor

Thanks @macloo, we'll take a look!

Contributor

gboone commented Mar 5, 2015

Thanks @macloo, we'll take a look!

@jcgallaher

This comment has been minimized.

Show comment
Hide comment
@jcgallaher

jcgallaher Mar 19, 2015

I use Linux and Vim 7.x. Vim runs on Mac and Windows. Server wise it's nice that Vim runs on the Linux server as well so you can port your customized Vim settings in both ends.

I use Linux and Vim 7.x. Vim runs on Mac and Windows. Server wise it's nice that Vim runs on the Linux server as well so you can port your customized Vim settings in both ends.

@gboone gboone referenced this issue Mar 24, 2015

Closed

My First Post #647

@wslack

This comment has been minimized.

Show comment
Hide comment
@wslack

wslack Apr 8, 2015

Member

Feedback: we shouldn't recommend that people install sublime text since that's in the laptop script.

Should we specify that the paste on this line should be in one line in the terminal?

Go to the terminal and paste the following curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/mac and press enter.

Member

wslack commented Apr 8, 2015

Feedback: we shouldn't recommend that people install sublime text since that's in the laptop script.

Should we specify that the paste on this line should be in one line in the terminal?

Go to the terminal and paste the following curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/mac and press enter.

@jbjonesjr

This comment has been minimized.

Show comment
Hide comment
@jbjonesjr

jbjonesjr Jun 22, 2015

Contributor

Hey everyone whose been following this article and related topics: I already have gotten this merged as a pull request last week, but in case you haven't checked out the article in a while (or wern't aware):

Google Code (listed as one of GitHub alternatives) is no longer accepting new projects, and will be ending support for existing projects over the next 6 months. This is definitely something to be aware when looking for hosting options (sourceforge, bitbucket, and the rest are all still available) for your open source projects.

/plugmode 🔌 As an FYI, Google Code provides a 1 button migration option to get your code to GitHub and keep it available after GCode shuts down. /plugmode

Contributor

jbjonesjr commented Jun 22, 2015

Hey everyone whose been following this article and related topics: I already have gotten this merged as a pull request last week, but in case you haven't checked out the article in a while (or wern't aware):

Google Code (listed as one of GitHub alternatives) is no longer accepting new projects, and will be ending support for existing projects over the next 6 months. This is definitely something to be aware when looking for hosting options (sourceforge, bitbucket, and the rest are all still available) for your open source projects.

/plugmode 🔌 As an FYI, Google Code provides a 1 button migration option to get your code to GitHub and keep it available after GCode shuts down. /plugmode

@hursey013

This comment has been minimized.

Show comment
Hide comment
@hursey013

hursey013 Apr 13, 2016

Member

Very possible that I messed something up, but it seems like at the point in the blog post where you run the laptop script it is missing the curl request to get the Brewfile. By following the steps in the blog, none of the software actually got installed for me and I got: "Error: No Brewfile found". It wasn't until I ran curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/Brewfile which is mentioned in the script instructions that it downloaded everything.

Member

hursey013 commented Apr 13, 2016

Very possible that I messed something up, but it seems like at the point in the blog post where you run the laptop script it is missing the curl request to get the Brewfile. By following the steps in the blog, none of the software actually got installed for me and I got: "Error: No Brewfile found". It wasn't until I ran curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/Brewfile which is mentioned in the script instructions that it downloaded everything.

@monfresh

This comment has been minimized.

Show comment
Hide comment
@monfresh

monfresh Apr 13, 2016

Member

@hursey013 That makes sense. The curl step was added recently to the laptop script. It would probably be best for the tutorial to point to the README as opposed to listing the installation steps directly since they could change.

Member

monfresh commented Apr 13, 2016

@hursey013 That makes sense. The curl step was added recently to the laptop script. It would probably be best for the tutorial to point to the README as opposed to listing the installation steps directly since they could change.

@gboone gboone closed this Sep 2, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment