Re: [PATCH] README: improve README formatting and clarity

["Darrick J. Wong" <djwong@kernel.org>]

On Tue, Nov 11, 2025 at 06:56:58AM -0500, Ravi Singh wrote:
> - Standardize shell command prompts with '$' for readability

The commands are supposed to be run in a root shell, so '#' is more
appropriate, because '#' is the root shell prompt.

--D

> - Correct minor typos
> - Clarify instructions for running tests.
> 
> Signed-off-by: Ravi Singh <ravising@redhat.com>
> ---
>  README | 44 ++++++++++++++++++++++++--------------------
>  1 file changed, 24 insertions(+), 20 deletions(-)
> 
> diff --git a/README b/README
> index 9e9afe3c..6edcdf31 100644
> --- a/README
> +++ b/README
> @@ -216,6 +216,8 @@ Setup Environment
>  5. Copy local.config.example to local.config and edit as needed. The TEST_DEV
>     and TEST_DIR are required.
>  
> +   $ cp local.config.example local.config
> +
>  6. (optional) Create fsgqa test users and groups:
>  
>     $ sudo useradd -m fsgqa
> @@ -241,13 +243,13 @@ Setup Environment
>  
>  For example, to run the tests with loopback partitions:
>  
> -    # xfs_io -f -c "falloc 0 10g" test.img
> -    # xfs_io -f -c "falloc 0 10g" scratch.img
> -    # mkfs.xfs test.img
> -    # losetup /dev/loop0 ./test.img
> -    # losetup /dev/loop1 ./scratch.img
> -    # mkdir -p /mnt/test && mount /dev/loop0 /mnt/test
> -    # mkdir -p /mnt/scratch
> +    $ xfs_io -f -c "falloc 0 10g" test.img
> +    $ xfs_io -f -c "falloc 0 10g" scratch.img
> +    $ mkfs.xfs test.img
> +    $ losetup /dev/loop0 ./test.img
> +    $ losetup /dev/loop1 ./scratch.img
> +    $ mkdir -p /mnt/test && mount /dev/loop0 /mnt/test
> +    $ mkdir -p /mnt/scratch
>  
>  The config for the setup above is:
>  
> @@ -316,7 +318,7 @@ Tools specification:
>        test, if the kernel supports kmemleak.
>   - fsstress:
>      - Set FSSTRESS_AVOID and/or FSX_AVOID, which contain options added to
> -      the end of fsstresss and fsx invocations, respectively, in case you wish
> +      the end of fsstress and fsx invocations, respectively, in case you wish
>        to exclude certain operational modes from these tests.
>   - core dumps:
>      - Set COREDUMP_COMPRESSOR to a compression program to compress crash dumps.
> @@ -378,25 +380,27 @@ ______________________
>  
>  Running tests:
>  
> -    - cd xfstests
> +    - $ cd xfstests-dev
>      - By default the tests suite will run all the tests in the auto group. These
>        are the tests that are expected to function correctly as regression tests,
>        and it excludes tests that exercise conditions known to cause machine
>        failures (i.e. the "dangerous" tests).
> -    - ./check '*/001' '*/002' '*/003'
> -    - ./check '*/06?'
> -    - Groups of tests maybe ran by: ./check -g [group(s)]
> +          $ ./check
> +    - Running specific tests:
> +          $ ./check '*/001' '*/002' '*/003'
> +          $ ./check '*/06?'
> +    - Groups of tests maybe ran by: $ ./check -g [group(s)]
>        See the tests/*/group.list files after building xfstests to learn about
>        each test's group memberships.
>      - If you want to run all tests regardless of what group they are in
> -      (including dangerous tests), use the "all" group: ./check -g all
> -    - To randomize test order: ./check -r [test(s)]
> +      (including dangerous tests), use the "all" group: $ ./check -g all
> +    - To randomize test order: $ ./check -r [test(s)]
>      - You can explicitly specify NFS/AFS/CIFS/OVERLAY, otherwise
>        the filesystem type will be autodetected from $TEST_DEV:
> -        - for running nfs tests: ./check -nfs [test(s)]
> -        - for running afs tests: ./check -afs [test(s)]
> -        - for running cifs/smb3 tests: ./check -cifs [test(s)]
> -        - for overlay tests: ./check -overlay [test(s)]
> +        - for running nfs tests: $ ./check -nfs [test(s)]
> +        - for running afs tests: $ ./check -afs [test(s)]
> +        - for running cifs/smb3 tests: $ ./check -cifs [test(s)]
> +        - for overlay tests: $ ./check -overlay [test(s)]
>            The TEST and SCRATCH partitions should be pre-formatted
>            with another base fs, where the overlay dirs will be created
>  
> @@ -438,7 +442,7 @@ Test script environment:
>  	    $TEST_DEV.
>  
>  	(b) mkfs a new XFS filesystem on $SCRATCH_DEV, and mount this
> -	    on $SCRATCH_MNT. Call the the _require_scratch function
> +	    on $SCRATCH_MNT. Call the _require_scratch function
>              on startup if you require use of the scratch partition.
>              _require_scratch does some checks on $SCRATCH_DEV &
>              $SCRATCH_MNT and makes sure they're unmounted. You should
> @@ -507,7 +511,7 @@ Test script environment:
>  	initialise the test environment correctly, the the build infrastructure
>  	also scans the test files for _begin_fstests invocations. It does this
>  	to compile the group lists that are used to determine which tests to run
> -	when `check` is executed. In other words, test files files must call
> +	when `check` is executed. In other words, test files must call
>  	_begin_fstest with their intended groups or they will not be run.
>  
>  	However, because the build infrastructure also uses _begin_fstests as
> -- 
> 2.51.1
> 
>