About README.md files.

Readme File Formatting

When you create a new repository though GitHub, select “Initialize this repository with a README” unless you plan to import an existing repository. Your README.md file is now available for editing in your brand-new repository. Your project’s name is at the top, followed by any description you chose to include when creating the repository. For this example, we will operate on the README.MD file. It is a common open source software practice to include a README file in the root of a git repository as documentation source for the project. Git blame README.MD. Executing the above command will give us our first sample of blame output. A great README file helps your project to stand out from the sea of open-source software on GitHub. A README is like the face of your project. It is the first file a person should read when encountering a source tree, and it should be written as a very brief and giving very basic introduction to the software.

Overview

README.md files are Markdown files that describe a directory.GitHub and Gitiles renders it when you browse the directory.

For example, the file /README.md is rendered when you view the contents of thecontaining directory:

https://github.com/google/styleguide/tree/gh-pages

Also README.md at HEAD ref is rendered by Gitiles when displaying repositoryindex:

https://gerrit.googlesource.com/gitiles/

Git Readme Example

Guidelines

README.md files are intended to provide orientation for engineers browsingyour code, especially first-time users. The README.md is likely the firstfile a reader encounters when they browse a directory thatcontains your code. In this way, it acts as a landing page for the directory.

We recommend that top-level directories for your code have an up-to-dateREADME.md file. This is especially important for package directories thatprovide interfaces for other teams.

Filename

Use README.md.

Files named README are not displayed in the directory view in Gitiles.

Contents

At minimum, every package-level README.md should include or point to thefollowing information:

1. What is in this package/library and what’s it used for.
2. Who to contact.
3. Status: whether this package/library is deprecated, or not for generalrelease, etc.
4. More info: where to go for more detailed documentation, such as:
   • An overview.md file for more detailed conceptual information.
   • Any API documentation for using this package/library.

Example