diff --git a/README.rst b/README.rst index a0476023..230c897c 100644 --- a/README.rst +++ b/README.rst @@ -5,8 +5,8 @@ .. image:: https://raw.githubusercontent.com/sahib/rmlint/develop/docs/_static/logo.png :align: center -`rmlint` finds space waste and other broken things on your filesystem and offers -to remove it. +``rmlint`` finds space waste and other broken things on your filesystem and +offers to remove it. .. image:: https://readthedocs.org/projects/rmlint/badge/?version=latest :target: http://rmlint.rtfd.org @@ -62,8 +62,8 @@ elsewhere. INSTALLATION ------------ -Chances are that you might have `rmlint` already as readily made package in your -favourite distribution. If not, you might consider +Chances are that you might have ``rmlint`` already as readily made package in +your favourite distribution. If not, you might consider `compiling it from source `_. DOCUMENTATION @@ -86,7 +86,7 @@ Sometimes we can be reached via IRC: ``#rmlint`` on ``irc.freenode.net``. BUGS ---- -If you found bugs, having trouble running `rmlint` or want to suggest new +If you found bugs, having trouble running ``rmlint`` or want to suggest new features please `read this `_. Also read the `BUGS `_ section of the `manpage `_ @@ -103,12 +103,12 @@ Here's a list of developers to blame: =================================== ============================= =========================================== There are some other people that helped us of course. -Please see the AUTHORS distributed along `rmlint`. +Please see the AUTHORS distributed along ``rmlint``. LICENSE ------- -`rmlint` is licensed under the conditions of the +``rmlint`` is licensed under the conditions of the `GPLv3 `_. See the `COPYING `_ diff --git a/docs/rmlint.1.rst b/docs/rmlint.1.rst index 296fe0a7..d70c80b0 100644 --- a/docs/rmlint.1.rst +++ b/docs/rmlint.1.rst @@ -72,7 +72,7 @@ General Options :``-T --types="list"`` (**default\:** *defaults*): - Configure the types of lint rmlint will look for. The `list` string is a + Configure the types of lint rmlint will look for. The ``list`` string is a comma-separated list of lint types or lint groups (other separators like semicolon or space also work though). @@ -256,15 +256,16 @@ General Options :``-y --sort-by=order`` (**default\:** *none*): - During output, sort the found duplicate groups by criteria described by `order`. - `order` is a string that may consist of one or more of the following letters: + During output, sort the found duplicate groups by criteria described by + ``order``. ``order`` is a string that may consist of one or more of the + following letters: - * `s`: Sort by size of group. - * `a`: Sort alphabetically by the basename of the original. - * `m`: Sort by mtime of the original. - * `p`: Sort by path-index of the original. - * `o`: Sort by natural found order (might be different on each run). - * `n`: Sort by number of files in the group. + * ``s``: Sort by size of group. + * ``a``: Sort alphabetically by the basename of the original. + * ``m``: Sort by mtime of the original. + * ``p``: Sort by path-index of the original. + * ``o``: Sort by natural found order (might be different on each run). + * ``n``: Sort by number of files in the group. The letter may also be written uppercase (similar to ``-S / --rank-by``) to reverse the sorting. Note that ``rmlint`` has to hold @@ -273,7 +274,7 @@ General Options :``-w --with-color`` (**default**) / ``-W --no-with-color``: Use color escapes for pretty output or disable them. - If you pipe `rmlints` output to a file ``-W`` is assumed automatically. + If you pipe ``rmlint``'s output to a file ``-W`` is assumed automatically. :``-h --help`` / ``-H --show-man``: @@ -290,7 +291,7 @@ Traversal Options :``-s --size=range`` (**default\:** "1"): Only consider files as duplicates in a certain size range. - The format of `range` is `min-max`, where both ends can be specified + The format of ``range`` is ``min-max``, where both ends can be specified as a number with an optional multiplier. The available multipliers are: - *C* (1^1), *W* (2^1), B (512^1), *K* (1000^1), KB (1024^1), *M* (1000^2), *MB* (1024^2), *G* (1000^3), *GB* (1024^3), @@ -320,22 +321,22 @@ Traversal Options :``-l --hardlinked`` (**default**) / ``--keep-hardlinked`` / ``-L --no-hardlinked``: Hardlinked files are treated as duplicates by default (``--hardlinked``). If - ``--keep-hardlinked`` is given, `rmlint` will not delete any files that are - hardlinked to an original in their respective group. Such files will be + ``--keep-hardlinked`` is given, ``rmlint`` will not delete any files that + are hardlinked to an original in their respective group. Such files will be displayed like originals, i.e. for the default output with a "ls" in front. The reasoning here is to maximize the number of kept files, while maximizing the number of freed space: Removing hardlinks to originals will not allocate any free space. - If `--no-hardlinked` is given, only one file (of a set of hardlinked files) - is considered, all the others are ignored; this means, they are not + If ``--no-hardlinked`` is given, only one file (of a set of hardlinked + files) is considered, all the others are ignored; this means, they are not deleted and also not even shown in the output. The "highest ranked" of the set is the one that is considered. :``-f --followlinks`` / ``-F --no-followlinks`` / ``-@ --see-symlinks`` (**default**): ``-f`` will always follow symbolic links. If file system loops occurs - ``rmlint`` will detect this. If `-F` is specified, symbolic links will be + ``rmlint`` will detect this. If ``-F`` is specified, symbolic links will be ignored completely, if ``-@`` is specified, ``rmlint`` will see symlinks and treats them like small files with the path to their target in them. The latter is the default behaviour, since it is a sensible default for @@ -393,8 +394,7 @@ Traversal Options Note that ``rmlint`` will find duplicates newer than ``timestamp``, even if the original is older. If you want only find duplicates where both - original and duplicate are newer than ``timestamp`` you can use - ``find(1)``: + original and duplicate are newer than ``timestamp`` you can use `find(1)`: * ``find -mtime -1 -print0 | rmlint -0 # pass all files younger than a day to rmlint`` @@ -440,24 +440,27 @@ Original Detection Options - **o**: keep file with lowest number of hardlinks outside of the paths traversed by ``rmlint``. - **O**: keep file with highest number of hardlinks outside of the paths traversed by ``rmlint``. - Alphabetical sort will only use the basename of the file and ignore its case. - One can have multiple criteria, e.g.: ``-S am`` will choose first alphabetically; if tied then by mtime. - **Note:** original path criteria (specified using `//`) will always take first priority over `-S` options. + Alphabetical sort will only use the basename of the file and ignore its + case. One can have multiple criteria, e.g.: ``-S am`` will choose first + alphabetically; if tied then by mtime. **Note:** original path criteria + (specified using ``//``) will always take first priority over ``-S`` + options. For more fine grained control, it is possible to give a regular expression to sort by. This can be useful when you know a common fact that identifies original paths (like a path component being ``src`` or a certain file ending). To use the regular expression you simply enclose it in the criteria string - by adding `` after specifying `r` or `x`. Example: ``-S - 'r<.*\.bak$>'`` makes all files that have a ``.bak`` suffix original files. + by adding ```` after specifying ``r`` or ``x``. Example: + ``-S 'r<.*\.bak$>'`` makes all files that have a ``.bak`` suffix original + files. Warning: When using **r** or **x**, try to make your regex to be as specific as possible! Good practice includes adding a ``$`` anchor at the end of the regex. Tips: - - **l** is useful for files like `file.mp3 vs file.1.mp3 or file.mp3.bak`. + - **l** is useful for files like ``file.mp3`` vs ``file.1.mp3`` or ``file.mp3.bak``. - **a** can be used as last criteria to assert a defined order. - **o/O** and **h/H** are only useful if there any hardlinks in the traversed path. - **o/O** takes the number of hardlinks outside the traversed paths (and @@ -756,9 +759,9 @@ FORMATTERS Available options: - * *omitfirst:* Same as the ``-f / --omitfirst`` option in ``fdupes(1)``. Omits the - first line of each set of duplicates (i.e. the original file. - * *sameline:* Same as the ``-1 / --sameline`` option in ``fdupes(1)``. Does not + * *omitfirst:* Same as the ``-f / --omitfirst`` option in `fdupes(1)`. Omits + the first line of each set of duplicates (i.e. the original file. + * *sameline:* Same as the ``-1 / --sameline`` option in `fdupes(1)`. Does not print newlines between files, only a space. Newlines are printed only between sets of duplicates. @@ -865,7 +868,7 @@ This is a collection of common use cases and other tricks: ``$ rmlint -e`` -* Do more complex traversal using ``find(1)``. +* Do more complex traversal using `find(1)`. ``$ find /usr/lib -iname '*.so' -type f | rmlint - # find all duplicate .so files`` diff --git a/docs/testing.rst b/docs/testing.rst index 6bca75f6..785f5842 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -29,7 +29,7 @@ variables which are: - ``RM_TS_PEDANTIC``: Run each test several times with different optimization options and check for errors between the runs. *(slow)*. - ``RM_TS_SLEEP``: Waits a long time before executing a command. Useful for - starting the testcase and manually running `rmlint` on the priorly generated + starting the testcase and manually running ``rmlint`` on the priorly generated testdir. - ``RM_TS_PRINT_CMD``: Print the command that is currently run. - ``RM_TS_KEEP_TESTDIR``: If a test failed, keep the test files. @@ -124,4 +124,5 @@ Rules def test_debian_support(): assert random.choice([True, False]): -* Unresolved issues can be marked with `known_issue` attribute to avoid failing automated travis testing +* Unresolved issues can be marked with the ``known_issue`` attribute to avoid + failing automated travis testing. diff --git a/docs/translators.rst b/docs/translators.rst index c48ac698..7c43d24e 100644 --- a/docs/translators.rst +++ b/docs/translators.rst @@ -78,4 +78,4 @@ gettext files: $ scons gettext -Then, proceed to work with the relevant `*.po` file as described above. +Then, proceed to work with the relevant ``*.po`` file as described above. diff --git a/docs/tutorial.rst b/docs/tutorial.rst index ea622841..2c36de09 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -535,14 +535,14 @@ precedence over any ``-S`` options. Alphabetical sort will only use the basename of the file and ignore its case. One can have multiple criteria, e.g.: ``-S am`` will choose first alphabetically; if tied then by mtime. -**Note:** original path criteria (specified using `//`) will always take first priority over `-S` options. +**Note:** original path criteria (specified using ``//``) will always take first priority over ``-S`` options. For more fine grained control, it is possible to give a regular expression to sort by. This can be useful when you know a common fact that identifies original paths (like a path component being ``src`` or a certain file ending). To use the regular expression you simply enclose it in the criteria string -by adding `` after specifying `r` or `x`. Example: ``-S +by adding ```` after specifying ``r`` or ``x``. Example: ``-S 'r<.*\.bak$>'`` makes all files that have a ``.bak`` suffix original files. Warning: When using **r** or **x**, try to make your regex to be as specific @@ -550,7 +550,7 @@ as possible! Good practice includes adding a ``$`` anchor at the end of the rege **Tips:** -- **l** is useful for files like `file.mp3 vs file.1.mp3 or file.mp3.bak`. +- **l** is useful for files like ``file.mp3`` vs ``file.1.mp3`` or ``file.mp3.bak``. - **a** can be used as last criteria to assert a defined order. - **o/O** and **h/H** are only useful if there any hardlinks in the traversed path. - **o/O** takes the number of hardlinks outside the traversed paths (and @@ -700,7 +700,7 @@ added to the count. This will of course lead to unmerged directories. That's why the ``-D`` option implies the ``-r`` (``--hidden``) and ``-l`` (``--hardlinked``) option in order to make this convenient. -A note to symbolic links: The default behaviour with --merge-directories is to +A note to symbolic links: The default behaviour with ``--merge-directories`` is to not follow symbolic links, but to compare the link targets. If the target is the same, the link will be the same. This is a sane default for duplicate directories, since twin copies often are created by doing a backup of some files. In this case @@ -770,11 +770,11 @@ The usage of the ``--replay`` feature is best understood by example: Options that are related to traversing and hashing/reading have no effect. Those are: - * `--followlinks` - * `--algorithm and --paranoid` - * `--clamp-low` - * `--hardlinked` - * `--write-unfinished` + * ``--followlinks`` + * ``--algorithm`` and ``--paranoid`` + * ``--clamp-low`` + * ``--hardlinked`` + * ``--write-unfinished`` * all other caching options. Miscellaneous options