README

   1 These are the GNU core utilities.  This package is the union of
   2 the GNU fileutils, sh-utils, and textutils packages.
   3
   4 Most of these programs have significant advantages over their Unix
   5 counterparts, such as greater speed, additional options, and fewer
   6 arbitrary limits.
   7
   8 The programs that can be built with this package are:
   9
  10   [ arch b2sum base32 base64 basename basenc cat chcon chgrp chmod chown
  11   chroot cksum comm coreutils cp csplit cut date dd df dir dircolors dirname
  12   du echo env expand expr factor false fmt fold groups head hostid hostname
  13   id install join kill link ln logname ls md5sum mkdir mkfifo mknod mktemp
  14   mv nice nl nohup nproc numfmt od paste pathchk pinky pr printenv printf ptx
  15   pwd readlink realpath rm rmdir runcon seq sha1sum sha224sum sha256sum
  16   sha384sum sha512sum shred shuf sleep sort split stat stdbuf stty sum sync
  17   tac tail tee test timeout touch tr true truncate tsort tty uname unexpand
  18   uniq unlink uptime users vdir wc who whoami yes
  19
  20 See the file NEWS for a list of major changes in the current release.
  21
  22 If you obtained this file as part of a "git clone", then see the
  23 README-hacking file.  If this file came to you as part of a tar archive,
  24 then see the file INSTALL for general compilation and installation
  25 instructions, or README-install for system and coreutils specific instructions.
  26
  27 Like the rest of the GNU system, these programs mostly conform to
  28 POSIX, with BSD and other extensions.  For closer conformance, or
  29 conformance to a particular POSIX version, set the POSIXLY_CORRECT
  30 and the _POSIX2_VERSION environment variables, as described in
  31 the documentation under "Standards conformance".
  32
  33 The ls, dir, and vdir commands are all separate executables instead of
  34 one program that checks argv[0] because people often rename these
  35 programs to things like gls, gnuls, l, etc.  Renaming a program
  36 file shouldn't affect how it operates, so that people can get the
  37 behavior they want with whatever name they want.
  38
  39 Special thanks to Paul Eggert, Brian Matthews, Bruce Evans, Karl Berry,
  40 Kaveh Ghazi, and François Pinard for help with debugging and porting
  41 these programs.  Many thanks to all of the people who have taken the
  42 time to submit problem reports and fixes.  All contributed changes are
  43 attributed in the commit logs.
  44
  45 And thanks to the following people who have provided accounts for
  46 portability testing on many different types of systems: Bob Proulx,
  47 Christian Robert, François Pinard, Greg McGary, Harlan Stenn,
  48 Joel N. Weber, Mark D. Roth, Matt Schalit, Nelson H. F. Beebe,
  49 Réjean Payette, Sam Tardieu.
  50
  51 Thanks to Michael Stone for inflicting test releases of this package
  52 on Debian's unstable distribution, and to all the kind folks who used
  53 that distribution and found and reported bugs.
  54
  55 Note that each man page is now automatically generated from a template
  56 and from the corresponding --help usage message.  Patches to the template
  57 files (man/*.x) are welcome.  However, the authoritative documentation
  58 is in texinfo form in the doc directory.
  59
  60
  61 ***************
  62 Feature requests:
  63 ---------------
  64
  65 If you would like to add a new feature, please try to get some sort of
  66 consensus that it is a worthwhile change.  One way to do that is to send
  67 mail to coreutils@gnu.org including as much description and justification
  68 as you can.  Based on the feedback that generates, you may be able to
  69 convince us that it's worth adding.  Please also consult the list of
  70 previously discussed but ultimately rejected feature requests at:
  71 https://www.gnu.org/software/coreutils/rejected_requests.html
  72
  73
  74 ***************
  75 Reporting bugs:
  76 ---------------
  77
  78 Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org.
  79 To suggest a patch, see the files README-hacking and HACKING for tips.
  80
  81 All of these programs except 'test' recognize the '--version' option.
  82 When reporting bugs, please include in the subject line both the package
  83 name/version and the name of the program for which you found a problem.
  84
  85 If you have a problem with 'sort', try running 'sort --debug', as it
  86 can often help find and fix problems without having to wait for an
  87 answer to a bug report.  If the debug output does not suffice to fix
  88 the problem on your own, please compress and attach it to the rest of
  89 your bug report.
  90
  91 IMPORTANT: if you take the time to report a test failure,
  92 please be sure to include the output of running 'make check'
  93 in verbose mode for each failing test.  For example,
  94 if the test that fails is tests/df/df-P.sh, then you would
  95 run this command:
  96
  97   make check TESTS=tests/df/df-P.sh VERBOSE=yes SUBDIRS=. >> log 2>&1
  98
  99 For some tests, you can get even more detail by adding DEBUG=yes.
 100 Then include the contents of the file 'log' in your bug report.
 101
 102
 103 ***************************************
 104
 105 There are many tests, but nowhere near as many as we need.
 106 Additions and corrections are very welcome.
 107
 108 If you see a problem that you've already reported, feel free to re-report
 109 it -- it won't bother us to get a reminder.  Besides, the more messages we
 110 get regarding a particular problem the sooner it'll be fixed -- usually.
 111 If you sent a complete patch and, after a couple weeks you haven't
 112 received any acknowledgement, please ping us.  A complete patch includes
 113 a well-written ChangeLog entry, unified (diff -u format) diffs relative
 114 to the most recent test release (or, better, relative to the latest
 115 sources in the public repository), an explanation for why the patch is
 116 necessary or useful, and if at all possible, enough information to
 117 reproduce whatever problem prompted it.  Plus, you'll earn lots of
 118 karma if you include a test case to exercise any bug(s) you fix.
 119 Here are instructions for checking out the latest development sources:
 120
 121   https://savannah.gnu.org/git/?group=coreutils
 122
 123 For general documentation on the coding and usage standards
 124 this distribution follows, see the GNU Coding Standards at:
 125 https://www.gnu.org/prep/standards/
 126
 127 For any copyright year range specified as YYYY-ZZZZ in this package
 128 note that the range specifies every single year in that closed interval.
 129
 130
 131 ========================================================================
 132
 133 Copyright (C) 1998-2023 Free Software Foundation, Inc.
 134
 135 Permission is granted to copy, distribute and/or modify this document
 136 under the terms of the GNU Free Documentation License, Version 1.3 or
 137 any later version published by the Free Software Foundation; with no
 138 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 139 Texts.  A copy of the license is included in the "GNU Free
 140 Documentation License" file as part of this distribution.