Learning Version Control with GitHub

• Part 1: Why Use Version Control?
• Part 2: Using GitHub
• Part 3: Working with Repositories
• Part 4: Markdown and Code
• Part 5: Managing Repositories

---

Markdown and Code

As discussed in the previous section, files added to the local folder or directory are monitored by the GitHub Desktop application. These new files can be uploaded to GitHub by pushing commits that also describe what was changed and how those changes fit into the larger project.

Before the new file was added in the previous section, however, there was already a file there. When the project was forked (cloned from another source), this file was carried forward from the original to the current repository. This was the README file.

README

When looking at a repository on GitHub, the text shown to other users comes from its README file. This is part of every project and should explain what the other files are and include additional information on how to use them.

Many README files also have information on the project, its goals, and how it could be used with other tools and projects. As the first source of information, the README should, ideally, explain everything a user needs to know.

Markdown

The README (and other files) are written in a language called markdown. This is named as something of a joke. While others like HTML “mark-up” text, this language “marks-down” the text.

Markdown supports many of the same ideas of languages like HTML. It has multiple levels of headings.

It supports giving text emphasis and making it bold as well.

Ordered and unordered lists are also supported. Unlike HTML and CSS, however, spacing becomes important for sub-items. They should start at least two spaces in or at least a standard tabbed distance to indicate they are sub-items of another, higher-level item.

Adding Code

Open the README file with Atom or another editor that understands markdown. (If the editor understands markdown, its color-coding will help when writing code and in understanding how it is applying different styles to text.)

Adding new markdown code will be shown in the editor (if it understands markdown) in a different color. Save the file after adding new markdown.

Opening the GitHub Desktop application will show those new changes to the file. Before the changes can be added to the GitHub repo, it needs a summary, description, and to be committed.

As reviewed in the previous section, clicking on “Push origin” after creating a new commit will send the changes to the GitHub repo.

Changes to the README file, once pushed to the public repo, will appear on the project page.

Making Small Changes to README and Other Files

While most changes should happen through something like the GitHut Desktop or another application, many (but not all) files can be changed through the “Edit this file” functionality when viewing the individual file on GitHub.

Because GitHub understands markdown, editing files written in the language allows for seeing a preview of those changes.

Changes can be made and then previewed before, like all other updates, writing a summary and description of the changes in a commit and submitting it to the repo.