Name Date Size

..29-Nov-20194 KiB

.gitattributesH A D13-Aug-201775

.gitignoreH A D15-Mar-2018323

.gitmodulesH A D17-Dec-201881

.x-update-copyrightH A D20-Jan-201956

AUTHORSH A D13-Aug-20171.3 KiB

bootstrapH A D01-Jan-202032.8 KiB

bootstrap.confH A D01-Jan-20206.3 KiB

build-aux/H01-Jan-20204 KiB

cfg.mkH A D01-Jan-202011.7 KiB

ChangeLog-2013H A D30-Oct-2017418.5 KiB

configure.acH A D01-Jan-202011.6 KiB

COPYINGH A D26-Jul-201834.3 KiB

doc/H01-Jan-20204 KiB

find/H01-Jan-20204 KiB

gnulib/H13-Aug-20174 KiB

gnulib-local/H13-Aug-20174 KiB

init.cfgH A D01-Jan-202019.1 KiB

lib/H01-Jan-20204 KiB

locate/H01-Jan-20204 KiB

m4/H01-Jan-20204 KiB

Makefile.amH A D01-Jan-20204.8 KiB

NEWSH A D01-Jan-202082.1 KiB

po/H01-Jan-20204 KiB

READMEH A D01-Jan-20204.6 KiB

README-hackingH A D01-Jan-20209.1 KiB

stamp-h.inH A D13-Aug-201710

tests/H01-Jan-20204 KiB

THANKSH A D13-Aug-20171.5 KiB

TODOH A D01-Jan-20202.8 KiB

xargs/H01-Jan-20204 KiB

README

1This package contains the GNU find, xargs, and locate programs.  find
2and xargs comply with POSIX 1003.2, as far as I know (with the
3exception of the "+" modifier for the "-exec" action, which isn't
4implemented yet).  They also support a large number of additional
5options, some borrowed from Unix and some unique to GNU.
6
7See the file NEWS for a list of major changes in the current release.
8
9See the file INSTALL for compilation and installation instructions.
10
11If there is no file INSTALL, you must be looking at the checked-out
12source code instead of at an unpacked source tarball ("release").  In
13that case, you should first please read and follow the instructions in
14the file README-hacking.  Those instructions explain how to generate
15the auto-generated files needed to build findutils, and this includes
16generating the INSTALL file.
17
18To verify the GPG signature of the release, you will need the public
19key of the findutils maintainer.  You can download this from
20ftp://ftp.gnu.org/gnu/gnu-keyring.gpg.  Alternatively, you could query
21a PGP keyserver, but you will need to use one that can cope with
22subkeys containing photos.  Many older key servers cannot do this.  I
23use subkeys.pgp.net.  I think that one works.  See also the
24"Downloading" section of https://www.gnu.org/software/findutils/.
25
26Special configure options:
27
28--with-afs
29  Make find support "-fstype afs".  Requires /afs, /usr/afsws/lib, and
30/usr/afsws/include.  configure doesn't add AFS support
31automatically because it adds considerably to find's size, and the
32AFS libraries need -lucb on Solaris, which breaks find.
33
34DEFAULT_ARG_SIZE=<value>
35  If this environment variable is defined to a numeric expression
36during configure, it determines the default argument size limits used
37by xargs without -s, and by find, when spawning child processes.
38Otherwise, the default is set at 128 kibibytes.  If the system cannot
39support the default limit, the system's limit will be used instead.
40
41
42To gain speed, GNU find avoids statting files whenever possible.
43It does this by:
441. Checking the number of links to directories and not statting files
45that it knows aren't directories until it encounters a test or action
46that needs the stat info.
472.  Rearranging the command line, where possible, so that it can do
48tests that don't require a stat before tests that do, in hopes that
49the latter will be skipped because of a -o/-a conjunction.  (But it
50only does this where it will leave the output unchanged.)
51
52The locate program and its helper programs are derived (heavily
53modified) from James Woods' public domain fast-find code, which is
54also distributed with the 4.3BSD find.  Because POSIX.2 requires `find
55foo' to have the same effect as `find foo -print', the fast-find
56searching has been moved to a separate program, `locate'; the same
57thing has been done in 4.4BSD.  If you use locate, you should run the
58included `updatedb' script from cron periodically (typically nightly).
59
60The latest full release is available at
61ftp://ftp.gnu.org/gnu/findutils.
62
63The latest test release (if any) is available at
64ftp://alpha.gnu.org/gnu/findutils
65
66Discussion of the findutils package and ways to improve it takes place
67on the "bug-findutils" mailing list, which you can join by sending
68mail to bug-findutils-request@gnu.org.  An archive of patches to the
69bug-findutils mailing list is available at
70https://lists.gnu.org/r/bug-findutils/.
71
72Bug reports, suggested patches and enhancement requests for findutils
73should be logged at https://savannah.gnu.org/bugs/?group=findutils.
74
75Changes to the findutils code are sent to the findutils-patches
76mailing list.  To join, please send email to
77findutils-patches@gnu.org.  You are also welcome to send patches to
78that list, but unless you are a list subscriber, you won't be able to
79follow any resulting discussion.  An archive of posts to the
80findutils-patches mailing list is available at
81https://lists.gnu.org/r/findutils-patches/.
82
83See https://savannah.gnu.org/git/?group=findutils for instructions on
84how to use git to access the findutils source code.
85
86Mail suggestions and bug reports for these programs to
87bug-findutils@gnu.org.
88
89========================================================================
90
91Copyright (C) 1996-2020 Free Software Foundation, Inc.
92
93Permission is granted to copy, distribute and/or modify this document
94under the terms of the GNU Free Documentation License, Version 1.3 or
95any later version published by the Free Software Foundation; with no
96Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
97Texts.  A copy of the license is included in the "GNU Free
98Documentation License" file as part of this distribution.
99

README-hacking

1These notes intend to help people working on the checked-out sources.
2They don't apply when you are building from a distribution tarball.
3
4If you want to submit a patch, please start from checked-out sources
5rather than the source tarball.
6
7
8Prerequisites
9=============
10
11 * git (to check out both findutils and gnulib).
12 * A C compiler, linker and software development libraries (the standard
13   C library).  Any compiler compliant with the 1990 ISO C standard running
14   on a POSIX system should work.
15 * GNU Autoconf
16 * GNU Automake
17 * GNU m4
18 * GNU gettext
19 * GNU Dejagnu
20
21Dejagnu is in fact optional, but it's strongly recommended, since it is
22needed to run findutils' test suite (which is how you know that find
23works once it is built on your system).
24
25The configure program should tell you if you try to use a version of
26one of these tools which is not of a recent enough version.  The file
27tool-versions.txt indicates which version of each tool the current
28release was built and tested with.  This is included in the tar-file
29releases, but it's not checked in to git.
30
31
32Use the latest upstream sources
33===============================
34
351. Check out the findutils code
36
37  git clone git://git.sv.gnu.org/findutils
38
39This will download the whole repository, it's about 16MB once fetched.
40If you already have a copy you can refresh it with:
41
42  git checkout master  (to switch to your copy of the master branch)
43  git pull (to collect and merge changes)
44
452. Generate a gnulib installation within the findutils source tree
46
47 Change your working directory to the findutils source directory (that
48 is, the directory containing this file).   Then run the following
49 command:-
50
51    ./bootstrap
52
53 This command will use git to check out the version of gnulib which is
54 intended to work with the findutils source you already have (gnulib
55 is used as a git submodule).  The gnulib code itself is left in the
56 directory "gnulib".  The "gl" directory contains just the gnulib
57 files that findutils needs during the build process.
58
59 This will also run Autoconf and Automake to generate the "configure"
60 script and "Makefile.in" files.
61
623. Run "./configure" and "make" in the normal way.
63
64 If you have GNU libintl installed, you can just run "./configure".
65 Otherwise, run "./configure --disable-nls".
66
67You are now at the point where your local directory looks just like it
68would after building a source release, except that your copy is more
69up-to-date.
70
71*Before* you commit changes
72===========================
73
74In this project, we much prefer patches that automatically record
75authorship.  That is important not just to give credit where due, but
76also from a legal standpoint (see below).  To create author-annotated
77patches with git, you must first tell git who you are.  That information
78is best recorded in your ~/.gitconfig file.  Edit that file, creating
79it if needed, and put your name and email address in place of these
80example values:
81
82[user]
83  name = Joe X. User
84  email = joe.user@example.com
85
86
87Required format for check-in messages
88=====================================
89
90We use a specific style for check-in messages.  See "git log" for
91examples.  The format corresponds to the standard GNU ChangeLog
92format, but without date & author headers (since git provides this
93data) and without a left margin (since there are no headers).
94
95--- example begins ---
96Don't overflow sig_atomic_t for --max-procs.
97
98* xargs/xargs.c (__STDC_LIMIT_MACROS): Define __STDC_LIMIT_MACROS
99in order to ensure that <stdint.h> defines the SIG_ATOMIC_MAX
100macro, which we need.
101(MAX_PROC_MAX): Define this as the maximum allowed value of
102proc_max.
103(main): Show the value of MAX_PROC_MAX for --show-limits.
104(increment_proc_max): Don't increment proc_max beyond
105MAX_PROC_MAX.
106--- example ends ---
107
108There are several things to notice about this checkin message.  Most
109importantly, it begins with a single line summary of the whole change.
110This needs to be short.  It would be used as the subject line of
111patches mailed by "git send-email".  Some people begin that line with
112a one-word tag indicating what is affected (for example find: for
113changes to find, doc: to changes to the documentation, maint: for
114changes to the maintainer automation and so forth).
115
116All changes to a file are grouped together in an entry which begins with
117an asterisk (*) and the file name.  The name of the modified function
118(if any) follows immediately in parentheses followed by a colon.  If
119you're modifying a file for which "function" isn't the logical unit of
120organisation, use whatever seems most useful.  For example when
121modifying the Texinfo source, use the section name.
122
123After the colon, describe the change you made to that function.  If
124you made a related change mention the places you made that change,
125too.  If you made many individually small changes, you can summarise
126these if they're not individually interesting.  For example you could
127just say "Update all callers to remove this function argument".  If
128that change spans several files, mention the other files modified.
129
130Note for maintainers:
131Prior to pushing a commit in the name of someone else to the public
132Git repository, please check if that person has undergone the
133"Copyright assignment" process for GNU findutils described below, or -
134in case of a trivial change (<10 lines, cumulatively with all their
135previous contributions) - document that such paperwork is not required
136by adding this line to the commit message:
137
138  Copyright-paperwork-exempt: Yes
139
140
141Making commits locally
142======================
143
144You will normally find it much easier to work on a branch.  This
145allows you to maintain your changes and test them without being
146affected by changes on the trunk.
147
148To Make a "topic" branch for your change, do this:
149
150  git branch my-topic
151  git checkout my-topic
152
153You can then work on your branch as normal.
154
155To update your local repository, do this:
156
157  git checkout master
158  git pull
159
160Then, rebase your topic branch to take into account the upstream
161changes you just pulled:
162
163  git checkout my-topic
164  git rebase master
165
166There are some useful checks that git commit hooks will do for you,
167it's a good idea to enable these:
168
169  mv .git/hooks/pre-commit.sample .git/hooks/pre-commit
170
171
172Submitting patches
173==================
174
175If you plan to submit changes to findutils, please make sure you have
176read the GNU coding standard (https://www.gnu.org/prep/standards/).
177Some common things you might have forgotten to do are:
178
179 - document your change in both the manual pages and the Texinfo file
180 - re-run the test suite (with Dejagnu installed!)
181 - add a test case for the bug you're fixing or feature you're adding
182 - mention your fix or change (if it's significant) in the NEWS file
183 - commit using a descriptive commit message
184
185If you have patches, please generate them with "git format-patch" and
186mail them to these addresses:
187
188  bug-findutils@gnu.org, findutils-patches@gnu.org
189
190Here is a complete session
191
192  # set up your topic branch
193  git checkout master
194  git pull
195  git branch my-topic
196  git checkout my-topic
197
198  # update the code, documentation, test suite and change log, run tests
199  emacs xargs/xargs.c
200  emacs doc/find.texi xargs/xargs.1
201  emacs xargs/testsuite/Makefile.am  xargs/testsuite/xargs.gnu/blah.exp
202  make check
203  emacs NEWS
204
205  # make sure you didn't break anything
206  make syntax-check
207  make distcheck
208
209  # commit the change and send the patches.
210  git add -u
211  git commit
212  git rebase master
213  mkdir /tmp/patches
214  git format-patch -o /tmp/patches master..HEAD
215  git send-email --compose \
216      --to bug-findutils@gnu.org \
217      --cc findutils-patches@gnu.org /tmp/patches
218
219
220Copyright assignment
221====================
222
223If your change is significant (i.e., if it adds more than ~10 lines),
224then you'll have to have a copyright assignment on file with the FSF.
225Since that involves first an email exchange between you and the FSF,
226and then the exchange (FSF to you, then back) of an actual sheet of
227paper with your signature on it, and finally, some administrative
228processing in Boston, the process can take a few weeks (for
229contributors in some geographies, this can all be done electronically,
230saving a lot of time).
231
232The forms to choose from are in gnulib's doc/Copyright/ directory.
233If you want to assign a single change, you should use the file,
234doc/Copyright/request-assign.changes:
235
236    https://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.changes;hb=HEAD
237
238If you would like to assign past and future contributions to a project,
239you'd use doc/Copyright/request-assign.future:
240
241    https://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=doc/Copyright/request-assign.future;hb=HEAD
242
243You may make assignments for up to four projects at a time.
244
245In case you're wondering why we bother with all of this, read this:
246
247    https://www.gnu.org/licenses/why-assign.html
248
249
250========================================================================
251Copyright (C) 2009-2020 Free Software Foundation, Inc.
252
253Permission is granted to copy, distribute and/or modify this document
254under the terms of the GNU Free Documentation License, Version 1.3 or
255any later version published by the Free Software Foundation; with no
256Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
257A copy of the license is included in the ``GNU Free Documentation
258License'' file as part of this distribution.
259