Month: February 2017

How to setup your GitHub credentials (and handle 2FA) on Windows using GitHub Desktop – 038

If you are a Windows user, install GitHub Desktop. It “automagically” (my new favorite word of the day) sets up your credentials, including 2FA.

You are not forced to use the GitHub Desktop UI once you’ve installed it. I mention this because before I started using GitHub Desktop, I didn’t know if Desktop would play nicely alongside the command line. Actually, GitHub Desktop makes using a command line interface even easier! (stay tuned for tomorrow’s tip).

First, you’ll login using your GitHub.com username and password.

GitHub Desktop login screen

Next, you’ll be prompted for you 2FA code.

Two-factor authentication prompt

And the you’re all set! So even if you want to go back to using the command line, you still can! Just check out tomorrow’s tip.

GitHub Desktop - Get started screen

Desktop also does a bunch of other stuff for you that we’ll get to later in this tip of the day series.

How to still create a Pull Request for a branch in your forked repo if the recently pushed branches button isn’t showing – 037

Suppose you no longer see the message to Compare & pull request your recently pushed branches (as shown below), but you still want to create a Pull Request.

There are 2 other ways to create a Pull Request.

Option #1 – use the Branches list in your repo

Your recently pushed branches: created-readme

You can go to the Branches listing in your repo,

branches link to see all branches

and for the branch you wish to create a new pull request for, click on the

Create New pull request button for a given branch

And now you’ll be shown the Open Pull Request form with the same defaults as before. Note again as yesterday, you’re taken to the base repo to open the pull request.

Pull Request form showing merging created-readme branch into base fork master branch

Option #2 – Manually create a Pull Request via the Pull Request tab

I like doing thing manually to truly appreciate what is happening behind the scenes.

First, in your forked repo (e.g. saraford-tips/your-moment-of-github-zen) go to the Pull Requests tab.

pull requests tab on forked repo

Then click on the New pull request button.

New pull request button

Yeah, I’m Captain Obvious here with that above screenshot! But notice what happens. You are again taken to the Open Pull Request page on the base repository.

Pull Request form showing merging created-readme branch into base fork master branch

How to turn on word wrap when editing a file on GitHub.com – 036

If you like to write, you’ll often run into the text not auto-wrapping, especially on markdown documentation files.

Whenever you run into a case where the line isn’t wrapping, just look up and you’ll see the option to change the Line wrap mode from No wrap to Soft wrap.

No wrap line wrap mode button

Changing to Soft warp now shows the line wrapped.

Soft wrap showing where the line has been wrapped

I had to look up the difference between soft wrap and hard wrap, since I thought “why not just name it No wrap vs Wrap?” But I guess they wanted to be explicit in saying that this option wasn’t going to insert actual line breaks.

How to submit a pull request to a forked repo whenever you are ready – 035

Continuing yesterday’s scenario of how to submit a new or updated README.md file to a repo that you’ve forked, let’s say you weren’t ready to fill out the Pull Request. You cancelled the Pull Request form by navigating away from that page. Perhaps you wanted to fix some typos, or you wanted to see how other people filled out their Pull Requests to provide the base fork repo maintainer the most adequate information possible.

Today, you’re ready to submit your changes.

Using saraford-tips/your-moment-of-github-zen as an example, you should still see Your recently pushed branches message bar at the top of your repo. A future tip shows how to manually generate the pull request if you don’t see this message bar.

Your recently pushed branches: created-readme

If you click, Compare & pull request, you’ll see the following screen.

My biggest ah-ha! moment when working with pull requests came to me when I finally noticed that the repo name changes when creating a pull request. Notice in the screenshot that you are no longer on your repo. You are now in the base repo (e.g. saraford/your-moment-of-github-zen).

Remember, a Pull Request is the start of a conversation, and you’re starting that conversation on the base repo. You are going to where they are to start the conversation, versus having them come to you.

Pull Request form showing merging created-readme branch into base fork master branch

The second ah-ha! moment came after I learned to chill out seeing all these dropdowns!

Unlike previous tips where you handled your own merges (via a Pull Request, since that’s the only way to merge via GitHub.com UI), you only saw the base: and compare: branch dropdown boxes. But remember, this time you’re involving a different repo. Because you now need to specify the repo for each branch, there’s twice as many dropdown boxes involved!

Aside: Something that drives me crazy is that I keep thinking the base fork branch should say created-readme, instead of master, because I’m thinking that I want my created-readme branch to show up as a branch on the base fork. It’s like I’m scared the PR will do an automatic merge or something. The best way to understand what is happening when you create a Pull Request is to see it from the maintainer’s point of view, which we’ll get to in future tips. But for now, trust that the defaults are correct. And to skip ahead, what will happen is after the PR is created, you might think that people (either the contributor or maintainer) will see the created-readme as a branch off of the branch: switcher, but this is not the case. The branch isn’t part of this repo. For the maintainer to see the branch, they have to actually clone it from the forked repo, (i.e. user saraford will have to pull from saraford-tips forked repo to get the code for the branch.) So again, a Pull Request is the start of a conversation that says, “Hey maintainer! Go over to this contributor’s repo and pull down their branch from over there!” Another way to think about why the base branch should be master and not created-readme, think of your merges via GitHub.com UI within your own repo. You wouldn’t try to merge created-readme to created-readme. You’d want to merge created-readme into the base branch master, exactly like you’re trying to do here, except that this time it is across repos. Hopefully my thinking out loud is helpful to someone! Smile

The pull request form you see below will be what people will see when they go to the base repo (in this case saraford/your-moment-of-github-zen) and open the pull request item listed in the pull request tab.

The defaults suggest using the content of the last commit, just so it isn’t a blank Pull Request. However, I tend to write my pull requests like I write my text messages, although IRL I use emojis, I swear!! #olds Smile

Open Pull Request form filled out like an email introduction

Now click Create pull request to open the Pull Request in the base repo, as shown in the image below.

Note the image below is from the contributor’s point of view (e.g. in this scenario it is from saraford-tips point of view).

Pull Request #1 listed in base repo

If you don’t see the Compare & pull request message box shown above (the first image in this blog post), it’s no big deal. You can still manually create a Pull Request via the Pull Request tab. Stay tuned. My design goal for the Tip of the Day is One tip == One button click, ideally.

How to create or update a readme from a forked repo on your own repo- 034

I love writing about code, so it pains me whenever I don’t see instructions how to get started. Let’s say you are like me and you want to add a readme to a project you’ve forked. This tips covers how to commit your new README.md file to your local repo first, so then you can propose it to the original repo. That’s how GitHub works.

Navigate to your forked copy, e.g. saraford-tips/your-moment-of-github-zen that I’m using for this demo. (the original repo is at saraford/your-moment-of-github-zen. Perhaps I should have used a more distinguishable name for these tips, sigh.)

At the bottom of the files listed you’ll see a button to Add a README. Clicking this button will automatically create a new file called README.md, as if you had manually clicked the Create new file button yourself.

Click Add a README at bottom

Clicking the Add a README button brings you to the README.md new file page.

Enter some instructions and make sure to preview for any Markdown formatting typos!

install instructions preview in readme.md file

After your proposed readme looks the way you want, you’ll scroll down to the Commit section and fill out the information about the commit accordingly. Note that in the below image, I selected a new branch for this commit and I renamed the branch to created-readme.

It is a matter of convention whether you commit to master or commit to a branch. Both are technically possible (doing a PR from master or doing a PR from a branch), but it is more of a social coding norm to commit to a branch. The idea is that master should always be your last known good, stable release. Proposed work or work in progress should be made on branches.

Create a new branch selected in commit form

Now click propose new file.

You haven’t actually “proposed the new file” yet. All you have done is committed the new README.md file to your local repo.

The GitHub workflow here is designed for someone who wants to submit the Pull Request immediately, but you don’t have to submit the Pull Request right now. Suppose you need to go back and make some edits. You’ve seen in previous tips that you can cancel out of this Pull Request form (by navigating anywhere else away from this page) and making any necessary edits on your created-readme branch.

I’ll pause this tip here. My style is to have these tips as short and to the point as possible about what each piece of functionality does, rather than how to use each piece of functionality in end-to-end scenarios.

How to fork a repo on GitHub – 033

There are two primary reasons why you’d want to fork a repo.

  1. You want to submit a patch, or as the kids call it today, a Pull Request.
  2. You want to experiment with changes and save them up to your forked GitHub repo.

In yesterday’s tip, I opened an Issue about my your-moment-of-github-zen electron app not being usable on Windows. In the upcoming tips, you’ll see how you can fork a repo and submit a pull request. But first, you’ll need a fork of the repo.

Go to the Fork button located at the top right of the repo

Fork button in the upper right of a repo

Clicking the Fork button will display a message asking you to wait a few seconds…

Forking saraford/your-moment-of-zen wait message

When finished, you’ll notice that your new GitHub repo looks similar as before, but with one key difference. Under the name of the repo you’ll see “forked from” with the name of the repo you’ve forked this from.

repo has footnote that this was forked

How to paste an image directly into an Issue on GitHub – 032

If you don’t know today’s tip, be prepared for a life-changing event (provided you are using Chrome).

Suppose you want to open an Issue on a project on GitHub. For example, let’s say you were learning Electron and tried out my your-moment-of-github-zen app on a Windows machine. You’ll quickly noticed that I wrote it on a Mac environment.

App appears offscreen on Windows

First, you can go to the repo, click on the Issue tab, (search to make sure there are no duplicate issues), and then fill out steps to reproduce the issue.

Place the cursor where you want the new image to go, and press Ctrl-v (or your non-Windows equivalent of paste).

Creating a new issue in repo

Not only will you see that the file was uploaded to GitHub, but also the Ctrl-v shortcut generated the markdown for showing images.

image uploaded and markdown generated

To make sure the image is :+1: click on the Issue – Preview tab.

image appears in preview

If you are not using Chrome, you’ll only see two options listed at the bottom of an Issue comment field.

pasting images not supporting in non-Chrome browsers

meaning you’ll have to save the file locally and then drag and drop it into the comment box (or use the Open File Dialog from the selecting them link).