diskuvbox
A basic, cross-platform set of commands to manipulate and query the file
system. Available with a liberal open-source license as a single
binary (diskuvbox, or diskuvbox.exe on
Windows) or as an OCaml library with minimal dependencies.
The single binary design is similar to
busybox. You can choose to
run a command like diskuvbox copy-file or (PENDING) make a symlink fromdiskuvbox to copy-file; either way the "copy-file" tooling will be invoked.
diskuvbox meet the following standards:
Any printed output will be the same on all operating systems with the default
options. For example the file search command find-up will
print files it finds ina/b/cformat, even on Windows. You will only get
operating system specific behavior (ex. printinga\b\con Windows) if you
use options like--native. Feel comfortable using the diskuvbox commands
in CRAM tests and expect scripts.On Windows, any failing command will provide a helpful error message if the
paths are over the Windows default 260 character pathname limit.For advanced embedding scenarios, the OCaml bytecode form of
diskuvboxwill
only dynamically load shared libraries
that are present in standard OCaml installations: dllunix, dllthreads and dllcamlstr.
Quick Links
| Section | Page |
| ------------ | ---------------------------------------------------------------------- |
| Usage | Add as an Opam Dependency |
| Usage | Using in Dune cram tests |
| Usage | Using in Opam build steps |
| Usage | Using in Dune rules |
| Box Commands | Box Commands |
| Box Library | Box Library |
| Contributing | Your Contributions |
Usage
Add as an Opam Dependency
If you are an OCaml developer who creates or maintains an Opam package, add
the following to your .opam file:
depends: [
# ...
"diskuvbox" {>= "0.1.0"}
]
or the following to your dune-project if Dune auto-generates your opam files:
(package
; ...
(depends
; ...
(diskuvbox (>= 0.1.0))
)
)
Using in Dune cram tests
FIRST, make sure you understand and have enabled Dune Cram Tests.
SECOND, make sure you have Added diskuvbox as an Opam Dependency.
FINALLY, go ahead and use diskuvbox in your .t cram tests like so:
Use your program. We'll pretend for this example that your program
creates a complex directory structure.
$ install -d a/b/c/d/e/f
$ install -d a/b2/c2/d2/e2/f2
$ install -d a/b2/c3/d3/e3/f3
$ install -d a/b2/c3/d4/e4/f4
$ install -d a/b2/c3/d4/e5/f5
$ install -d a/b2/c3/d4/e5/f6
$ touch a/b/x
$ touch a/b/c/y
$ touch a/b/c/d/z
Use diskuvbox to print the directory tree. It should be reproducible
on any platform that Diskuv Box supports!
$ diskuvbox tree a --max-depth 10 --encoding UTF-8
a
├── b/
│ ├── c/
│ │ ├── d/
│ │ │ ├── e/
│ │ │ │ └── f/
│ │ │ └── z
│ │ └── y
│ └── x
└── b2/
├── c2/
│ └── d2/
│ └── e2/
│ └── f2/
└── c3/
├── d3/
│ └── e3/
│ └── f3/
└── d4/
├── e4/
│ └── f4/
└── e5/
├── f5/
└── f6/
Using in Opam build steps
FIRST, make sure you have Added diskuvbox as an Opam Dependency.
SECOND, if you are sure that you only need diskuvbox for Opam build steps,
change your .opam file so it has a {build} filter. For example:
depends: [
# ...
"diskuvbox" {>= "0.1.0" & build}
]
or in your dune-project if you auto-generate your .opam files:
(package
; ...
(depends
; ...
(diskuvbox (and (>= 0.1.0) :build))
)
)
FINALLY, go ahead and use diskuvbox in your .opam build steps like:
build: [
# ...
["diskuvbox" "copy-file-into" "assets/icon.png" "assets/public.gpg" "%{_:share}%"]
]
Using in Dune rules
FIRST, make sure you have Added diskuvbox as an Opam Dependency.
THEN, go ahead and use diskuvbox as (run diskuvbox ...) in the rules of
your dune files.
For example, in the source code for this project we have detailed dune rules
that ensure each OCaml source file always has our open-source Apache v2.0
license at the top. We use (run diskuvbox ...) so that our already complex
rules don't become even more complicated with platform specific hacks:
; This first rule creates "corrected" source code in the Dune build directory
; that always has an Apache v2.0 license at the top of each file.
(rule
(targets diskuvbox.corrected.ml diskuvbox.corrected.mli)
(deps
(:license %{project_root}/etc/license-header.txt)
(:conf %{project_root}/etc/headache.conf))
(action
(progn
; `headache` adds/replaces headers in source code. It is documented at
; https://github.com/Frama-C/headache/#readme
;
; 1. The `headache` program modifies files in-place, so we make a copy of
; the original file.
; 2. On Windows `heachache` can fail with "Permission denied" if we don't
; set write permissions on the file.
; `diskuvbox` can accomplish both goals on all its supported platforms.
(run diskuvbox copy-file -m 644 diskuvbox.ml diskuvbox.corrected.ml)
(run diskuvbox copy-file -m 644 diskuvbox.mli diskuvbox.corrected.mli)
; Add Apache v2.0 license to each file
(run headache -h %{license} -c %{conf} %{targets})
;
; `ocamlformat` is used so that our source code modification is idempotent.
; (Advanced: Options chosen so that continuous integration tests work with
; any version of `ocamlformat`.)
(run ocamlformat --inplace --disable-conf-files --enable-outside-detected-project %{targets}))))
; These second set of rules let us type:
; dune build @runlicense --auto-promote
;
; Anytime we type that Dune will take the corrected source code from the Dune
; build directory and use it to modify the original source code.
(rule
(alias runlicense)
(action
(diff diskuvbox.ml diskuvbox.corrected.ml)))
(rule
(alias runlicense)
(action
(diff diskuvbox.mli diskuvbox.corrected.mli)))
Box commands
| Command | Description |
| ------------------------------------------- | ------------------------------------------------------------------------- |
| copy-dir | Copy content of one or more source directories to a destination directory |
| copy-file | Copy a source file to a destination file |
| copy-file-into | Copy one or more files into a destination directory |
| find-up | Find a file in the current directory or one of its ancestors |
| touch | Touch one or more files |
| tree | Print a directory tree |
If you would like to add or modify a Box command, head over to
Your Contributions.
diskuvbox copy-dir
$ diskuvbox copy-dir --help
NAME
diskuvbox-copy-dir - Copy content of one or more source directories to
a destination directory.
SYNOPSIS
diskuvbox copy-dir [OPTION]... SRCDIR... DESTDIR
DESCRIPTION
Copy content of one or more SRCDIR... directories to the DESTDIR
directory. copy-dir will follow symlinks.
ARGUMENTS
DESTDIR (required)
Destination directory. If DESTDIR does not exist it will be
created.
SRCDIR (required)
One or more source directories to copy. The command fails when a
SRCDIR does not exist.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
copy-dir exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
diskuvbox copy-file
$ diskuvbox copy-file --help
NAME
diskuvbox-copy-file - Copy a source file to a destination file.
SYNOPSIS
diskuvbox copy-file [OPTION]... SRCFILE DESTFILE
DESCRIPTION
Copy the SRCFILE to the DESTFILE. copy-file will follow symlinks.
ARGUMENTS
DESTFILE (required)
Destination file. If DESTFILE does not exist it will be created.
SRCFILE (required)
The source file to copy. The command fails when a SRCFILE does not
exist.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
-m VAL, --mode=VAL
The chmod mode permission of the destination file, in octal. If
not specified then the chmod mode permission of the source file is
used. Examples: 644, 755.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
copy-file exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
diskuvbox copy-file-into
$ diskuvbox copy-file-into --help
NAME
diskuvbox-copy-file-into - Copy one or more files into a destination
directory.
SYNOPSIS
diskuvbox copy-file-into [OPTION]... SRCFILE... DESTDIR
DESCRIPTION
Copy one or more SRCFILE... files to the DESTDIR directory.
copy-files-into will follow symlinks.
ARGUMENTS
DESTDIR (required)
Destination directory. If DESTDIR does not exist it will be
created.
SRCFILE (required)
One or more source files to copy. The command fails when a SRCFILE
does not exist.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
-m VAL, --mode=VAL
The chmod mode permission of the destination file, in octal. If
not specified then the chmod mode permission of the source file is
used. Examples: 644, 755.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
copy-file-into exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
diskuvbox find-up
$ diskuvbox find-up --help
NAME
diskuvbox-find-up - Find a file in the current directory or one of its
ancestors.
SYNOPSIS
diskuvbox find-up [OPTION]... FROMDIR BASENAME...
DESCRIPTION
Find a file that matches the name as one or more specified FILE...
files in the FROMDIR directory.
Will print the matching file if found. Otherwise will print nothing.
ARGUMENTS
BASENAME (required)
One or more basenames to search. The command fails when a BASENAME
is blank or has a directory separator.
FROMDIR (required)
Directory to search. The command fails when FROMDIR does not
exist.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
--native
Print files and directories in native format. On Windows the
native format uses backslashes as directory separators, while on
Unix (including macOS) the native format uses forward slashes. If
--native is not specified then all files and directories are
printed with the directory separators as forward slashes.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
find-up exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
diskuvbox touch
$ diskuvbox touch --help
NAME
diskuvbox-touch-file - Touch one or more files.
SYNOPSIS
diskuvbox touch-file [OPTION]... FILE...
DESCRIPTION
Touch one or more FILE... files.
ARGUMENTS
FILE (required)
One or more files to touch. If a FILE does not exist it will be
created.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
touch-file exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
diskuvbox tree
$ diskuvbox tree --help
NAME
diskuvbox-tree - Print a directory tree.
SYNOPSIS
diskuvbox tree [OPTION]... DIR
DESCRIPTION
Print the directory tree starting at the DIR directory.
ARGUMENTS
DIR (required)
Directory to print. The command fails when DIR does not exist.
OPTIONS
--color=WHEN (absent=auto)
Colorize the output. WHEN must be one of `auto', `always' or
`never'.
-d VAL, --max-depth=VAL (absent=0)
Maximum depth to print. A maximum depth of 0 will never print
deeper than the name of the starting directory. A maximum depth of
1 will, at most, print the contents of the starting directory.
Defaults to 0
-e VAL, --encoding=VAL (absent=ASCII)
The encoding of the graphic characters printed: ASCII, UTF-8.
Defaults to ASCII
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of `auto',
`pager', `groff' or `plain'. With `auto', the format is `pager` or
`plain' whenever the TERM env var is `dumb' or undefined.
--native
Print files and directories in native format. On Windows the
native format uses backslashes as directory separators, while on
Unix (including macOS) the native format uses forward slashes. If
--native is not specified then all files and directories are
printed with the directory separators as forward slashes.
-q, --quiet
Be quiet. Takes over -v and --verbosity.
-v, --verbose
Increase verbosity. Repeatable, but more than twice does not bring
more.
--verbosity=LEVEL (absent=warning)
Be more or less verbose. LEVEL must be one of `quiet', `error',
`warning', `info' or `debug'. Takes over -v.
--version
Show version information.
EXIT STATUS
tree exits with the following status:
0 on success.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
Contributions
Head over to Your Contributions.
Acknowledgements
The first implementations of Diskuv Box were implemented with the assistance of
the OCaml Software Foundation (OCSF),
a sub-foundation of the INRIA Foundation.
Two OCaml libraries (bos and
cmdliner) are essential to Diskuv Box;
these libraries were created by Daniel Bünzli.
Status
| Status |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| |
| |
sha256=dff845dd043f627a74c1cf17ba8320344af8665df8464a0b5679c0b36a09e777
sha512=cc8265a60909f0d4e9e42e2684b8673748206470ea6519dd892ede4d9f7d80bb2431617e910d7c0fc765f5b6288e7aa4068c05917d8729fdee8d84feff604186
>= "0.19.0" & build
>= "1.05" & build
>= "1.1.0" & build
>= "1.0.0"
>= "2.0.0" & with-test
>= "0.7.0"
>= "0.8.9"
>= "0.2.0"
>= "5.2.1"
>= "4.10.0"
>= "1.5.3" & with-doc
>= "2.9"