AREADMEfile containsdescriptive information about the content of adirectory in which the file is located. The scope of the information generally includes the files of the directory, and may include descendant directories, or even the full directory tree. The name is intended to draw auser's attention to important and orientational information about the directory content. Arule of thumb for one unfamiliar with the content of a directory is to read the README file before other files. Although the name README is often used, there are many other similar names used for the same purpose including "Read Me" and "READ.ME". Sometimes the file name includes anextension to indicate thefile format such as "README.txt" forplain text or "README.md" forMarkdown.[1] The file's name is oftenall caps.
A README file in anarchive acts the same as in a directory since an archive is like a directory that is stored as a single file.
Lacking standardization, the format and content of a README file varies dramatically. For asoftware project, a README file commonly includes information such as:
The convention of including a README file began in the mid-1970s.[3][4][5][6][7][8][9] InUnix, where most file names were in lowercase, the name was capitalized so it would stand out and appear near the beginning ofASCII-ordered lists. EarlyMacintosh system software installed a Read Me on the Startup Disk, and README files commonly accompanied third-party software.
In particular, there is a long history offree software andopen-source software including a README file; theGNU Coding Standards encourage including one to provide "a general overview of the package".[10]
Since the advent of theweb as ade facto standard platform forsoftware distribution, many software packages have moved (or occasionally, copied) some of the above ancillary files and pieces of information to awebsite orwiki, 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.
The popularsource code hosting websiteGitHub strongly encourages the creation of a README file – if one exists in the main (top-level) directory of a repository, it is automatically presented on the repository's front page.[11] In addition to plain text, various other formats andfile extensions are also supported,[12] and HTML conversion takes extensions into account – in particular a README.md is treated asGitHub Flavored Markdown.
Directory content metadata is sometimes stored in files in addition to or instead of a README.[13] The following table lists commonly-used file names along with content of what is commonly in the file. As with README, there are no formal standards that govern the file names nor the content of them. Yet, there are conventions as dictated byGnits Standards andGNU Autotools.
| README | General information |
| AUTHORS | Credits |
| 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 |
| CONTRIBUTING/HACKING | Guide for prospective contributors to the project |
| FAQ | Frequently asked questions and answers |
| TODO | Planned changes |
Hacker's-eye introduction traditionally included in the top-level directory of a Unix source distribution, containing a pointer to more detailed documentation, credits, miscellaneous revision history, notes, etc. […] When asked, hackers invariably relate the README convention to the famous scene in Lewis Carroll's Alice's Adventures In Wonderland in which Alice confronts magic munchies labeled "Eat Me" and "Drink Me".
[README.TXT is the DOC file for SPICE/SINC/SLIC] This failsafe tape contains the circuit analysis programs SPICE SINC and SLIC described in the Applications Software Bulletin Volume 4. requirements: SPICE requires FORTRAN-10 version 4 because of its use of Right adjusted Holerith data. Executes in about 47K. […] it also includes this file, the FOROTS to go with the SAVes and the source for SECOND.MAC, the timing routine. SPICE is broken into three parts: 1SPICE.FOR, 2 and 3. There is a printed document to describe each of the programs. These are included in the DECUS packet. The documentation and programs were originally developed by the E.E. department of the Univ. of Calif. at Berkeley on a CDC 6400. Except to convert the FORTRAN to the DECsystem-10 no changes have been made to the programs. For the test data SLIC and SINC have shown a slight variation with respect to the 6400, SPICE shows no variation. Good luck! Ashley Grayson 27-NOV-74 [end of README.TXT]
The files on this FAILSAFE tape constitute the UCI LISP system. They are for the most part documented in the UCI LISP Manual, available from the Department of Information and Computer Science at the University of California, Irvine, California.[1]
[…] they had READMEs (actual physical printed files) for all of their punch cards and mag tape and pretty much anything else that was a "program". At that time you really needed one because of the labourous process that was involved with getting the created, ran, and everything else. These READMEs sometimes also included the actual printouts of how the punch cards were supposed to be punched as a form of error checking and debugging. The convention apparently also follows the old system in that with all the punch cards a "reem" of paper was attached with the statement README in caps printed on it, this had all of the instructions for use and loading of the punch cards into the system. For a time reference, this would have been in the 60s. […]
This article is based in part on theJargon File, which is in the public domain.