Practical Git: Document repos with README files

Trevor Miller
InstructorTrevor Miller

Share this video with your friends

Send Tweet
Published 7 years ago
Updated 4 years ago

A Git repo is much more useful when you know what it is; it has become a convention to add a README markdown file to the root of your repos which explains what the project is as well as anything else you want to add. In this lesson we create a file and push it to our remote repo for others to see.

[00:00] Here we're inside of a Git repo called Utility Functions. To create a README, we can create a file called README. The convention is to use a markdown file, so we add the .md for markdown extension. I've opened up this file in my code editor, and now let's create a description for the project here.

[00:24] It's also common and helpful to provide some code examples in your README, so I'll make an examples header. Then I'll add a code snippet. Now we have a simple document at the root of our project that has a description of what the project is as well as a few code examples.

[00:42] There are lots of other things that you can put in your README as well as lots of other markdown syntax that you can learn, like these examples here. The important thing is that no matter what, at least, have a simple README that explains what your repo is for. Now let's do a Git status, and we'll see that our README is untracked.

[01:01] Let's stage it, and then we'll create a commit. We'll say, "Adding README." Then let's push it to our remote repo. Now if we look at our repo on our GitHub page, we can see if we scroll down that our README is being rendered. It says, "A collection of utility functions," and then it has a few code examples from the document that we created...