12 amazing features of GitHub

For the life of me, I can't think of any intro, so...

#1 Editing code on GitHub.com

I’ll start with what I think everyone already knows (although I personally had no idea about it a week ago). When viewing any text file on GitHub, in any repository, you can see a small pencil at the top right. If you click on it, you can edit this file. Once complete, click Propose file change and GitHub will create a fork and Pull Request. Amazing, isn't it? He creates the fork himself! There is no need to fork and upload the code to yourself, make changes locally and send it back to GitHub with a Pull Request. Very convenient if you need to make minimal edits. not quite a real Pull Request

#2 Inserting images

Problem descriptions are not limited to just text comments. Did you know you can paste images directly from the clipboard? When pasted, you'll see it uploaded (to the cloud, no doubt) and turned into markup to display the image. Graceful!

#3 Code formatting

If you need to write a block of code, start with three backticks and GitHub will try to guess what programming language you're writing in. But if you're posting a piece of code in a programming language like Vue, Typescript, or JSX, you can explicitly specify the language so that the syntax highlighting is correct. Notice the ```jsx on the first line: ...ensuring the correct display of the code snippet: (This also applies to Gist, by the way. If you specify the .jsf extension for a gist, the JSF syntax will be highlighted). Here is a list of all supported syntaxes .

#4 Closing problems using “magic words” in Pull Requests

Let's say you create a Pull Request that fixes issue #234. You can insert the text "fixes issue #234" into your request description (or anywhere in any change request comment). After this, merging the Pull Request will “automatically” close the problem. Cool, isn't it? Here's more information about this in the documentation .

#5 Link to comments

Have you ever needed to create a link to a specific comment and didn't know how? Those days are long gone because I'll let you in on a secret: To create a link to a comment, you simply click on the date/time next to the title. Look, gaearon now has a photo!

#6 Code link

So you want to create a link to a specific line of code. In this case, try this: Click on the line number next to the desired code in the open file. Wow, see? The URL has changed, the line number is now visible in it! If you hold down the SHIFT key and click on another line number, then voila! – The URL will change again and the range of rows will be highlighted. This URL will now point to this file and this range of lines. But wait, it points to the current thread. What if the file changes? You probably need, in this case, a permanent link to the file in its current state. I'm very lazy, so I took one screenshot of all the above: By the way, about URLs...

#7 Using GitHub URL as Command Line

Navigating through GitHub using the UI is organized very conveniently. But sometimes, to get to a specific location, it's faster to just type it into the URL. For example, if I want to go to a branch I'm working on and see how it compares to master, I can simply type /compare/branchname after the repository name. This will take me to the diff page for that branch: But these are differences from the master branch, but if I worked with the integration branch before, I can enter /compare/integration-branch...my-branch in the URL For hotkey lovers: CTRL+L or CMD+L moves the cursor to the URL bar (at least in Chrome and Firefox browsers). This, combined with browser autocompletion, makes navigating between branches much easier. Pro tip: Use the arrows to navigate through Chrome's autocomplete suggestions, and press SHIFT+DELETE to remove items from history (for example, after merging a branch). (I don’t know if it would be easier to read these shortcut keys if I put a space in them, like SHIFT + DELETE. But technically “+” is not part of them, so I don’t like this option. It’s because of things like this I don't sleep at night, Rhonda.)

#8 Create lists for problems

Do you want a checkbox in your problem description? And do you want a nifty bar like “2 out of 5” to appear when you view an issue from the list? No problem! You can create interactive checkboxes using the following syntax:

• [ ] Screen width (integer)
• [x] Service worker support
• [x] Fetch support
• [ ] CSS flexbox support
• [ ] Custom elements

Syntax: space, hyphen, space, opening square bracket, space (or x), closing square bracket, space and some words. After that, you can actually check/uncheck these buttons! For some reason, this seems like some kind of technical magic to me. You can tick the boxes! And at the same time the source text changes! It's scary to think what they'll come up with next. Oh, and if this problem is in the project panel, then the progress will be displayed there too: If you don't understand what I mean by "project panel" - read below. Just a couple of centimeters lower on this page.

#9 Project panels in GitHub

For large projects I have always used Jira. And for my personal projects, I have always used Trello. I really like both of these tools. When I learned a few weeks ago that GitHub was offering its own option, right in the Projects tab of the repository, I thought it would make sense to duplicate the set of tasks I already work with in Trello. There is nothing funny here. And now the same thing in the GitHub project: Gradually your eyes will get used to the low-contrast image For the sake of speed, I've added all of the above as notes, meaning they are not "real" GitHub issues. But the power of issue management in GitHub lies in its integration with the rest of the repository - so it's probably better to add existing issues from the repository to the dashboard. Click Add Cards in the top right corner and find what you would like to add. This is where the special search syntax comes in handy : for example, type is:pr is:open and you can drag any open Pull Request onto the panel, or label:bug if you need to fix some bugs. You can also convert existing notes into issues. And finally, from the existing problem form, add it to the project in the right panel. It will go into the triage list of that project panel, so you can choose which column to put it in When the description of a “task” is in the same repository as the code implementing this task, it is very (very) convenient. This means that many years from now, you'll be able to run git blame on a line of code and figure out the entirety of the issue that led to that line, without having to track it all down in Jira/Trello/elsewhere.

Flaws

For the last three weeks I've been experimenting with doing everything in GitHub instead of Jira (on a small project, kind of Kanban style) and loving it. But I can't imagine this for a Scrum project where development speed and the like need to be assessed and calculated properly. The good news is that GitHub projects have so few "special features" that switching to another system won't take much time. So give it a try and see how much you like it. I don't know how important this is, but I heard about ZenHub and opened it for the first time 10 minutes ago. It's essentially an extension of GitHub where you can rate issues and create "epics" and dependencies. There are graphs of development speed and burnout; It looks like it's just an amazing thing. Further reading: GitHub documentation on Projects.

#10 Gwiki

For an unstructured set of pages—like Wikipedia—the GitHub Wiki (which I'll just call Gwiki from now on) is great. For a structured set of pages - for example, like your documentation - not so much. There is no way to indicate that “this page is a child of that one”; there are no such convenient things as “Next section” and “Previous section” buttons. Hansel and Gretel would definitely get lost here, because there are no “breadcrumbs” (special debugging operators - approx. trans.) here either. (Author's note: Have you read this story? It's just inhumane. Two young thugs kill a poor hungry old lady, burning her alive in her own oven . And of course, leaving a complete mess for no one to understand. I think that's why young people these days are so sensitive as hell – stories read to children at bedtime these days aren't cruel enough!) Moving on – to try out Gwiki for real, I entered a few pages from NodeJS as wiki pages, then created a custom sidebar to simulate the actual structure of the site. This sidebar is always there, although the current page is not highlighted. The links will have to be maintained manually, but overall everything works fine. If you want, you can take a look : This can hardly compete with something like GitBook (which is used in the Redux documentation ) or a bespoke website. But this is already a good 80% of it and everything is right in your repository. I'm just a fan of this. I suggest that if you've outgrown the single README.md file and need several different pages for user manuals or more detailed documentation, it makes sense to stick with Gwiki. If the lack of structure/navigation bothers you, move on to something else.

#11 GitHub Pages

You may already know that GitHub Pages can be used to host a static website. And if you didn’t know, then you know now. However, this section is dedicated to a more specific topic: using Jekyll to create a website. In its simplest form, GitHub Pages + Jekyll can render the README.md file using a nice looking theme. For example, take a look at my readme page from about-github : If you click on the settings tab for this GitHub site, enable GitHub Pages, and select the Jekyll theme... Then we will get a page in the style of the Jekyll theme : You can then create an entire static site based primarily on easily editable markup files, essentially turning GitHub into a CMS. Although I haven't actually used this, this is how websites are built using the Bootstrap framework using React, so there's nothing terrible about it. I note that Ruby must be running on the local machine (Windows users here will exchange understanding glances and go the other way, macOS users will say: “What’s the problem, where are you going? Ruby is a universal platform! There’s also a GEMS package management system!”) ( It's also worth noting that "Aggressive or threatening content or behavior" is not allowed on GitHub Pages, so you won't be able to post your version of the Hansel and Gretel story there).

My opinion

The more I looked into the GitHub Pages + Jekyll combination (for this article), the more I thought the whole idea smelt weird. The idea of ​​"making your own website with minimal effort" is great. But to work on it you still need the current version on the local machine. And for something so "simple" there are too many command line commands. I skimmed through the seven pages in the Getting Started section and felt like the only thing simple about it was me . And I haven’t even figured out the simple syntax for the main page or the basics of a simple “Templating Mechanism based on the Liquid language.” I'd rather write a website myself! To be honest, I'm a little surprised that Facebook is using this for React documentation when they could probably build their help system pages using React and pre-render as static HTML files every day . All they need to do is find a way to receive existing markup files as if they were coming from the CMS. What if...

#12 Using GitHub as a CMS

Let's say we have a website with some text, but we don't want to store that text as HTML markup. Instead, we'd like to store chunks of text somewhere that can be easily edited by non-developer users. Preferably with some versioning option. Perhaps even with some kind of peer review process. Here's what I suggest: use the markup files stored in the repository to store the text. And use a component in the client side that would retrieve these pieces of text and display them on the page. I'm a fan of React, so here's an example of a proper <Markdown> component that, given a path to a markdown file, will extract it, parse it, and render it as HTML.

class Markdown extends React.Component {
    constructor(props) {
      super(props);

      // Конечно, вам нужно заменить это на свой URL
      this.baseUrl = 'https://raw.githubusercontent.com/davidgilbertson/about-github/master/text-snippets';

      this.state = {
        markdown: '',
      };
    }

    componentDidMount() {
      fetch(`${this.baseUrl}/${this.props.url}`)
        .then(response => response.text())
        .then((markdown) => {
          this.setState({markdown});
        });
    }

    render() {
      return (
        <div dangerouslySetInnerHTML={{__html: marked(this.state.markdown)}} />
      );
    }
}

(I use the npm marked package here to parse markup in HTML) The URL points to my example repository, which contains markup files in the /text-snippets directory . (You can also use the GitHub API to fetch content , but I doubt you'll need that.) You could use a component like this like this:

const Page = () => (
  <div className="page">
    <div className="about-us">
      <Markdown url="about-us.md" />
    </div>

    <div className="disclaimer">
      <p>A very important disclaimer:</p>

      <Markdown url="disclaimers/home-page-disclaimer.md" />
    </div>
  </div>
);

So now GitHub acts as, in a way, your CMS for those pieces of text that you would like to host. The above example only retrieves the markup after the component is loaded in the browser. If you need a static site, you will have to render it on the server. Good news! There is nothing stopping you from retrieving all the markup files on the server (using whatever caching strategy you like). If you decide to go this route, it makes sense to use the GitHub API to get a list of all the markup files in a directory. Bonus - GitHub utilities! I've been using the Octotree Chrome extension for quite some time now and recommend it to you. Not without reservations, but I still recommend it. It displays a panel on the left with a tree view of the repository you are browsing. And from this video I learned about octobox , which also seems to me to be a very good utility so far. This is the inbox for your GitHub issues. That's all you need to know about him. Speaking of colors, I took all the above screenshots in a light theme so as not to scare you. But if I prefer dark colors in everything else, then why put up with deathly pale GitHub? Here I used a combination of the Stylish extension for the Chrome browser (which can apply themes to any website) and the GitHub Dark style . And for starters, the GitHub developer tools dark theme (built-in, you just need to enable it) and the Atom One Dark theme for Chrome.

Bitbucket

Strictly speaking, it's not entirely appropriate here, but I just can't help but mention Bitbucket. Two years ago I started a project and spent half a day choosing the best git hosting. So, Bitbucket won by a significant margin. Their code review pipeline is far ahead of the competition (this was long before GitHub even had the concept of a reviewer). Since then, GitHub has also acquired reviews. Unfortunately, I haven't had a chance to use Bitbucket for the last year - perhaps they have moved ahead in something again. So I recommend that those who are responsible for choosing a git hosting service also pay attention to Bitbucket.

Conclusion

That's all! I hope that I was able to tell you at least three things that were previously unknown to you. And I also hope that you had a good time reading my article.