World Library  
Flag as Inappropriate
Email this Article


Article Id: WHEBN0000594417
Reproduction Date:

Title: Readme  
Author: World Heritage Encyclopedia
Language: English
Subject: List of Touhou Project characters, Bunny plain.jpg, IBM Extended Density Format, Software art, How-to
Collection: Computer Files, Software Documentation
Publisher: World Heritage Encyclopedia


The README file for cURL

A readme (or read me) file contains information about other files in a directory or archive and is commonly distributed with computer software, forming part of its documentation. Such a file is usually a text file called README.TXT,, README.1ST, READ.ME, or simply README, although some Microsoft Windows software may occasionally include a README.WRI, README.RTF, or README.DOC. The name is chosen so that users unaware of the existence of this type of file would be drawn to read it.

README is traditionally written in upper case, so that on case-preserving environments that display files in an ASCIIbetical ordering by default, such as the ls command in Linux, the name will appear near the beginning of a directory listing (since upper-case letters sort before lower-case letters in ASCIIbetical ordering).


  • Contents 1
  • History 2
  • On GitHub 3
  • See also 4
  • Further reading 5
  • References 6


The contents typically include one or more of the following:

The expression "readme file" is also sometimes used descriptively and generically, whereby the files are not named "readme", but are considered types of readme files. The source code distributions of many free software packages, especially those following the Gnits Standards or those produced with GNU Autotools, include a standard set of readme files:

README General information
THANKS Acknowledgments
CHANGELOG A detailed changelog, intended for programmers
NEWS A basic changelog, intended for users
INSTALL Installation instructions
COPYING / LICENSE Copyright and licensing information
BUGS Known bugs and instructions on reporting new ones

Other files commonly distributed with software include a FAQ and a TODO file listing possible future changes.


Since the advent of the Internet as a de facto standard platform for software distribution, many software packages have moved (or occasionally, copied) some of the above ancillary files and pieces of information to a website or wiki, sometimes including the README itself, or sometimes leaving behind only a brief README file without all of the information required by a new user of the software. However, the popularity of GitHub (as well as older community conventions) has contributed towards README files still being widely-used in open-source software (see next section).

On GitHub

On GitHub, if a git repository has a README file in its main (top-level) directory, the README file is automatically converted into formatted HTML and presented on the main web page of the git repository, underneath the list of files and directories in the repository. Various different file extensions can be used,[2] but there should not be more than one file named "README" at the top-level of a GitHub repository. The conversion to HTML takes account of the file extension of the file – for example, naming the README file for a GitHub repository "" would cause GitHub to treat it as a GitHub-flavored Markdown file, which is also the default README file format on GitHub.

This makes using GitHub a low-effort way to create a web page for a git repository (GitHub also supports the publication of wikis and separate websites, which may be formatted however the developers want).

Because the GitHub web interface lets users edit a file in a relatively streamlined way, without manually cloning the repository and manually making a pull request, it supports wiki-style editing of the README file[3] – with approval necessary by a committer (i.e. someone who has write access to the repository) if the user is not a committer themselves.

However, within the GitHub app for Android mobile devices, the contents of README files are not shown underneath the list of files,[4] and nor are README files formatted as HTML when viewed.

See also

Further reading

  • Johnson, Mark (February 1997). "Building a Better ReadMe". Technical Communication (Society for Technical Communication) 44 (1): p28–36. 
  • Livingston, Brian (14 September 1998). "Check your Readme files to avoid common Windows problems". InfoWorld 20 (37): p34. 
  • Preston-Werner, Tom (23 Aug 2010). "Readme Driven Development".  
  • Streb, Claire (12 Sep 2015). "All Hail the README File!".  


  1. ^ a b Manes, Stephen (November 1996). "README? Sure--before I buy!". PC World 14 (11): p366. 
  2. ^ "Markup". GitHub. GitHub. 25 December 2014. Retrieved 8 February 2015. 
  3. ^ "Create A Repo". GitHub Help. GitHub. Retrieved 8 February 2015. 
  4. ^ "Issue 206". GitHub Android app. Retrieved 8 February 2015. 
  • This article is based in part on the Jargon File, which is in the public domain.
This article was sourced from Creative Commons Attribution-ShareAlike License; additional terms may apply. World Heritage Encyclopedia content is assembled from numerous content providers, Open Access Publishing, and in compliance with The Fair Access to Science and Technology Research Act (FASTR), Wikimedia Foundation, Inc., Public Library of Science, The Encyclopedia of Life, Open Book Publishers (OBP), PubMed, U.S. National Library of Medicine, National Center for Biotechnology Information, U.S. National Library of Medicine, National Institutes of Health (NIH), U.S. Department of Health & Human Services, and, which sources content from all federal, state, local, tribal, and territorial government publication portals (.gov, .mil, .edu). Funding for and content contributors is made possible from the U.S. Congress, E-Government Act of 2002.
Crowd sourced content that is contributed to World Heritage Encyclopedia is peer reviewed and edited by our editorial staff to ensure quality scholarly research articles.
By using this site, you agree to the Terms of Use and Privacy Policy. World Heritage Encyclopedia™ is a registered trademark of the World Public Library Association, a non-profit organization.

Copyright © World Library Foundation. All rights reserved. eBooks from Project Gutenberg are sponsored by the World Library Foundation,
a 501c(4) Member's Support Non-Profit Organization, and is NOT affiliated with any governmental agency or department.