In software distribution and software development, a README file contains information about the other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called README
, Read Me
, READ.ME
, README.txt
, [1] or README.md
(to indicate the use of Markdown)
The file's name is generally written in uppercase. On Unix-like systems in particular, this causes it to stand out –both because lowercase filenames are more common, and because the ls
command commonly sorts and displays files in ASCII-code order, in which uppercase filenames will appear first. [nb 1]
A README file typically encompasses:
The convention of including a README file began in the mid-1970s. [3] [4] [5] [6] [7] [8] [9] Early Macintosh 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 of free software and open-source software including a README file; the GNU Coding Standards encourage including one to provide "a general overview of the package". [10]
Since the advent of the web 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.
The popular source code hosting website GitHub 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 and file extensions are also supported, [12] and HTML conversion takes extensions into account –in particular a README.md
is treated as GitHub Flavored Markdown.
The expression "readme file" is also sometimes used generically, for other files with a similar purpose.[ citation needed ] For example, 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 |
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 |
Also commonly distributed with software packages are an FAQ file and a TODO
file, which lists planned improvements.
Ghostscript is a suite of software based on an interpreter for Adobe Systems' PostScript and Portable Document Format (PDF) page description languages. Its main purposes are the rasterization or rendering of such page description language files, for the display or printing of document pages, and the conversion between PostScript and PDF files.
A man page is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs, formal standards and conventions, and even abstract concepts. A user may invoke a man page by issuing the man
command.
In computing, tar is a computer software utility for collecting many files into one archive file, often referred to as a tarball, for distribution or backup purposes. The name is derived from "tape archive", as it was originally developed to write data to sequential I/O devices with no file system of their own, such as devices that use magnetic tape. The archive data sets created by tar contain various file system parameters, such as name, timestamps, ownership, file-access permissions, and directory organization. POSIX abandoned tar in favor of pax, yet tar sees continued widespread use.
In software development, Make is a command-line interface software tool that performs actions ordered by configured dependencies as defined in a configuration file called a makefile. It is commonly used for build automation to build executable code from source code. But, not limited to building, Make can perform any operation available via the operating system shell.
A changelog is a log or record of all notable changes made to a project. The project is often a website or software project, and the changelog usually includes records of changes such as bug fixes, new features, etc. Some open-source projects include a changelog as one of the top-level files in their distribution.
In computer programming, glob patterns specify sets of filenames with wildcard characters. For example, the Unix Bash shell command mv *.txttextfiles/
moves all files with names ending in .txt
from the current directory to the directory textfiles
. Here, *
is a wildcard and *.txt
is a glob pattern. The wildcard *
stands for "any string of any length including empty, but excluding the path separator characters ".
In Unix and Unix-like operating systems, iconv is a command-line program and a standardized application programming interface (API) used to convert between different character encodings. "It can convert from any of these encodings to any other, through Unicode conversion."
The GNU Core Utilities or coreutils is a package of GNU software containing implementations for many of the basic tools, such as cat, ls, and rm, which are used on Unix-like operating systems.
SCons is a computer software build tool that automatically analyzes source code file dependencies and operating system adaptation requirements from a software project description and generates final binary executables for installation on the target operating system platform. Its function is analogous to the traditional GNU build system based on the make utility and the autoconf tools.
Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.
In computing, more
is a command to view the contents of a text file one screen at a time. It is available on Unix and Unix-like systems, DOS, Digital Research FlexOS, IBM/Toshiba 4690 OS, IBM OS/2, Microsoft Windows and ReactOS. Programs of this sort are called pagers. more
is a very basic pager, originally allowing only forward navigation through a file, though newer implementations do allow for limited backward movement.
QGIS is a geographic information system (GIS) software that is free and open-source. QGIS supports Windows, macOS, and Linux. It supports viewing, editing, printing, and analysis of geospatial data in a range of data formats. QGIS was previously also known as Quantum GIS.
AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix manpages, e-books, slide presentations, etc. Common file extensions for AsciiDoc files are txt
and adoc
.
This is a comparison of notable free and open-source configuration management software, suitable for tasks like server configuration, orchestration and infrastructure as code typically performed by a system administrator.
Geany is a free and open-source lightweight GUI text editor using Scintilla and GTK, including basic IDE features. It is designed to have short load times, with limited dependency on separate packages or external libraries on Linux. It has been ported to a wide range of operating systems, such as BSD, Linux, macOS, Solaris and Windows. The Windows port lacks an embedded terminal window; also missing from the Windows version are the external development tools present under Unix, unless installed separately by the user. Among the supported programming languages and markup languages are C, C++, C#, Java, JavaScript, PHP, HTML, LaTeX, CSS, Python, Perl, Ruby, Pascal, Haskell, Erlang, Vala and many others.
Nix is a cross-platform package manager for Unix-like systems, and a tool to instantiate and manage those systems, invented in 2003 by Eelco Dolstra.
This comparison of optical character recognition software includes:
SMPlayer is a cross-platform graphical front-end for MPlayer and mpv and forks of Mplayer using GUI widgets offered by Qt. SMPlayer is free and open-source software subject to the terms of the GNU General Public License version 2 or later. SMplayer has been localized in more than 30 languages.
Wiki.js is a wiki engine running on Node.js and written in JavaScript. It is free software released under the Affero GNU General Public License. It is available as a self-hosted solution or using "single-click" install on the DigitalOcean and AWS marketplace.
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.
[…] 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 the Jargon File, which is in the public domain.