From e86a59971c8a809298ab68368ca5045c1b59366d Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Fri, 27 Nov 2015 13:43:01 +0100 Subject: m + add manpage + improve readme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 12 ++++++-- README | 73 +++++++++++++++++++++++---------------------- doc/man/bfind.1 | 75 +++++++++++++++++++++++++++++++++++++++++++++++ src/bfind.auto-completion | 2 +- 4 files changed, 122 insertions(+), 40 deletions(-) create mode 100644 doc/man/bfind.1 diff --git a/Makefile b/Makefile index de78779..3998b25 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,8 @@ BINDIR = $(PREFIX)/bin DATADIR = $(PREFIX)/share INFODIR = $(DATADIR)/info DOCDIR = $(DATADIR)/doc +MANDIR = $(DATADIR)/man +MAN1DIR = $(MANDIR)/man1 LICENSEDIR = $(DATADIR)/licenses COMMAND = bfind @@ -86,7 +88,7 @@ bin/bfind.%sh-completion: obj/bfind.auto-completion .PHONY: install-default -install-default: install-core install-info install-shell +install-default: install-core install-info install-man install-shell .PHONY: install install: install-core install-doc install-shell @@ -105,7 +107,7 @@ install-license: install -m644 -- COPYING LICENSE "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)" .PHONY: install-doc -install-doc: install-info install-pdf install-dvi install-ps +install-doc: install-info install-pdf install-dvi install-ps install-man .PHONY: install-info install-info: bin/bfind.info @@ -127,6 +129,11 @@ install-ps: bin/bfind.ps install -dm755 -- "$(DESTDIR)$(DOCDIR)" install -m644 $< -- "$(DESTDIR)$(DOCDIR)/$(PKGNAME).ps" +.PHONY: install-man +install-man: doc/man/bfind.1 + install -dm755 -- "$(DESTDIR)$(MAN1DIR)" + install -m644 $< -- "$(DESTDIR)$(MAN1DIR)/$(COMMAND).1" + .PHONY: install-shell install-shell: install-bash install-fish install-zsh @@ -160,6 +167,7 @@ uninstall: -rm -- "$(DESTDIR)$(DATADIR)/bash-completion/completions/$(COMMAND)" -rm -- "$(DESTDIR)$(DATADIR)/fish/completions/$(COMMAND).fish" -rm -- "$(DESTDIR)$(DATADIR)/zsh/site-functions/_$(COMMAND)" + -rm -- "$(DESTDIR)$(MAN1DIR)/$(COMMAND).1" diff --git a/README b/README index fe43022..186c069 100644 --- a/README +++ b/README @@ -1,49 +1,48 @@ -Minimalitic `find` using breadth-first crawling. +NAME + bfind - Minimalitic find using breadth-first crawling -The entire invocation syntax is: +SYNOPSIS + bfind [OPTION]... [--] [DIRECTORY] - bfind [--xdev] [--hardlinks] [--symlinks] \ - [--visible] [--print0] [--] [DIRECTORY] +DESCRIPTION + bfind is a minimalitic alternative to find(1) that is + designed to be efficient that locating files. To + accomplish this, bfind uses breadth-first crawling + instead of depth-first crawling. -With --xdev crawling will not be restricted to -one mount point. + bfind is only includes the bare minimum, a few options + for restricting the crawlspace and an option to output + visited files in a safe format rather than a human-friendly + format. bfind will never include all features of find(1) + because they are excessive and some other than makes not + since to have in the program and can be outright dangerous. -With --hardlinks bfind will be hardlink aware -on directories. +OPTIONS + -x, --xdev + Do not restrict crawling to one mount point. -With --symlinks bfind will visit directories -symlinks points, and directories will never -be revisited. Visited directories will be -memorised by absolute real path name. + -h, --hardlinks + Watch out for hardlinked directories. -With --visible no files starting with a dot -will be listed. + -s, --symlinks + Visit symbolically linked directories, but + never visit the same directory twice. -With --print0 a NUL (\0) character will be -printed at end of file names rather than -a LF (\n). + -v, --visible + No files starting with a dot will be listed. + -0, --print0 + Terminate lines with NUL rather than LF. -Short option alternatives: +RATIONALE + While bfind is not as fast as find(1) for large + hierarchies, it will probably give your results faster + if you are looking for a file (rather than listing files), + because the file you are looking for is probably + near the directory you are searching from. - -x --xdev - -h --hardlinks - -s --symlinks - -v --visible - -0 --print0 +SEE ALSO + find(1), grep(1) - Short options can be combined - - -Each line will always start with DIRECTORY. - - -Why bfind? While bfind is not as fast as find*, -it will probably give your results faster if -you are looking for a file (not list files), -because the file you are looking for is probably -near the directory you are searching from. - - -* For large hierarchies. + Full documentation available locally via: info '(bfind)' diff --git a/doc/man/bfind.1 b/doc/man/bfind.1 new file mode 100644 index 0000000..3265717 --- /dev/null +++ b/doc/man/bfind.1 @@ -0,0 +1,75 @@ +.TH BFIND 1 BFIND +.SH NAME +bfind - Minimalitic find using breadth-first crawling +.SH SYNOPSIS +.BR bfind +.RI [ OPTION ]... +[--] +.RI [ DIRECTORY ] +.IR PASSPHRASE_LIST +.SH DESCRIPTION +.BR bfind +is a minimalitic alternative to +.BR find (1) +that is designed to be efficient that locating files. +To accomplish this, +.BR bfind +uses breadth-first crawling instead of depth-first crawling. +.PP +.BR bfind +is only includes the bare minimum, a few options for +restricting the crawlspace and an option to output +visited files in a safe format rather than a human-friendly +format. +.BR bfind +will never include all features of +.BR find (1) +because they are excessive and some other than makes +not since to have in the program and can be outright +dangerous. +.SH OPTIONS +.TP +.BR \-x ,\ \-\-xdev +Do not restrict crawling to one mount point. +.TP +.BR \-h ,\ \-\-hardlinks +Watch out for hardlinked directories. +.TP +.BR \-s ,\ \-\-symlinks +Visit symbolically linked directories, but +never visit the same directory twice. +.TP +.BR \-v ,\ \-\-visible +No files starting with a dot will be listed. +.TP +.BR \-0 ,\ \-\-print0 +Terminate lines with NUL rather than LF. +.SH RATIONALE +While +.BR bfind +is not as fast as +.BR find (1) +for large hierarchies, it will probably give your +results faster if you are looking for a file (rather +than listing files), because the file you are looking +for is probably near the directory you are searching +from. +.SH "SEE ALSO" +.BR find (1), +.BR grep (1) +.PP +Full documentation available locally via: info \(aq(bfind)\(aq +.SH AUTHORS +Principal author, Mattias Andrée. See the COPYING file for the full +list of authors. +.SH LICENSE +Copyright \(co 2013, 2015 Mattias Andrée +.br +License GPLv3+: GNU GPL version 3 or later . +.br +This is free software: you are free to change and redistribute it. +.br +There is NO WARRANTY, to the extent permitted by law. +.SH BUGS +Please report bugs to https://github.com/maandree/passcheck/issues or to +maandree@member.fsf.org diff --git a/src/bfind.auto-completion b/src/bfind.auto-completion index f1f74e2..ecc95f8 100644 --- a/src/bfind.auto-completion +++ b/src/bfind.auto-completion @@ -1,6 +1,6 @@ (bfind (unargumented (options -x --xdev) (complete --xdev) - (desc 'Do not crawl across mount points')) + (desc 'Crawl across mount points')) (unargumented (options -h --hardlinks) (complete --hardlinks) (desc 'Be aware of hardlinked directories')) -- cgit v1.2.3-70-g09d2