Tag: repos

How to add a license to a repo (and have it be recognized) for an existing GitHub repo – 048

In yesterday’s tip, you saw how to select a license when you create a new project. Today’s tip is about how to get that license picker back for an existing repo.

Since licensing is done based on the content of a file named license in your repo, instead of metadata about the GitHub repository that lives alongside the repo, first, you’ll want to create a new file in your repo.

Create new file button 

Next, type in License and over to the right, the license dropdown button (re)appears. You can call the file license, license.md, LICENSE, or LICENSE.MD, as long as the filename is “license”

image

When you select a license, for example the MIT License,

Choose a License: MIT License

and you’ll see that the license text is inserted and some boilerplate information, like copyright year and name, are inserted.

MIT license showing copyright year and full username

Now when you commit this file (and wait a minute or so), you’ll see that GitHub now displays the license name at the top of the repo.

MIT license displayed at top of repo above language bar

Suppose you didn’t choose a license via the dropdown picker (either on /new or in the method described above). Suppose you’ve previously pushed a license file up to GitHub at some prior point.

GitHub uses an open source project called Licensee to do license detection, i.e. compare the license file to the list of licenses coming from the Choose a License website. According to the GitHub blog, “Licensee is the same code we use to provide the Licenses API and understand how repositories on GitHub are licensed.”

If you want to contribute to licensee, there’s a contributing guide in the repo. If you’re looking to add a new license that can be detected, you’ll want to check out the choose a license repo.

How to add a license (and choose your own licensing adventure) when you first create a repository on GitHub – 047

For the longest time, I thought it was required that you select a README in order to select a license. Although you should have both (ideally) in your repo, you don’t have to create a readme file on the /new page just to set a license file.

In the image below, the Initialize this repository with a README is unchecked, while the MIT License is being selected for the Add a license dropdown button.

adding MIT License without the Initialize this repo with a README checked

Remember, just like a readme, the license for your GitHub repo is only a file that’s within the repo itself (and doesn’t automatically get added to a Visual Studio solution – something that took me a long time to wrap my head around).

LICENSE file shown in repo file listing

But suppose you know you need a license, but want to go over what your options are. There’s a (?) button right next to the Add a license dropdown button on the /new page.

choose a license help icon

Clicking on this help icon button will take you the Choose a License website, a “choose your own adventure”-style site where you can learn more about licensing!

Got a suggestion for the Choose a License website? The website (a github pages site) is an open source project accepting contributions!

Down in the bottom right corner of the footer, you see a link to the repo

Curated with <3 by GitHub, Inc. and You!

I call out this link because adding the “and You!” link was my first ever Pull Request. These Pull Request-related tips won’t really click until you’ve walked through submitting a Pull Request yourself. I hope by sharing my lightbulb experiences from my first few PRs that it will help others get a sense of what the process is like.

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 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 view a diff for a commit as files side by side on GitHub – 028

Personally, I’m not a fan of the inline diffs that make you do homework to figure out what’s being added and what’s being removed.

For example, if you go to the Code – Commits page and click on the commit id for a given commit, as shown in the illustration below,

Code - Commits page clicking on a commit id

You’re taken to a page that shows the diffs as inline or unified for the file.

diff of readme.md that's shown unified

Fortunately, there’s a split button in the upper right hand corner that says Unified | Split.

Clicking on Split portion of the button will show the before and after changes side by side, which is just my personal preference.

diff showing changes before and after side by side

How to view the diffs for a specific commit for a specific branch in GitHub – 027

Suppose you want to see what changed between two commits on a particular branch. First, you can go to the Code tab and change the desired branch (see previous tips on how to do this).

Next click Commits link,

Commits link being clicked on Code page

and navigating to the desired commit, you can click on the commit id (as highlighted in the image below).

Fixed compile error commit id button highlighted

Now you can see all the changes for that particular commit.

Showing 1 changed file with 3 additions and 3 deletions

How to view all files in a repo for a given commit on a given branch on GitHub.com – 026

I’m purely a visual person. I cannot put clothes into a dresser drawer. If it is out of sight; it’s out of mind. It’s that bad. Thus being able to view all the files in a repo for a given commit really helped drive home how Git is so different from other source control systems.

Going back to my random-example repo, suppose you want to see the state of the repo as of the first commit on master.

Navigate to the Code tab and make sure master is selected. (If you want to view the state of a repo for a commit on a different branch, use this Branch:master dropwdown button to change to desired branch.)

Viewing list of commits under Code tab master branch

Now scroll all the way down to the original commit. You’ll see highlighted in the next image a <> button that displays a tooltip Browse the repository at this point in the history.

initial commit - Browser the repository at this point in the history button highlighted

Clicking on this <> button takes you back to what looks exactly like the repo homepage, but with one key difference…

repo display list of files for tree:ad98b093dd

Instead of branch:master or branch:readme-draft, you’re now seeing this Tree:ad98b093 thingy.

What’s a tree? This question gets into the internals of Git, which we will learn together this year! To be honest, all I know right now is that every Git commit has a tree, so this dropdown button label is saying, “show me the files for this commit id.” You’ll also notice that

Lastest commit ad98b09 3 days ago

You’ll see that this Tree:ad98b093 commit id matches the id in the far right.

You might be wondering why the dropdown doesn’t show the list of all the possible trees to view. My guess is this list would be come unmanageable pretty quickly. And people probably don’t need to look up the state of a repo at a given snapshot very often.