S3UTILS-211: Update README with configurable replication status

Author: tcarmet

README.md

@@ -243,15 +243,48 @@ and aborts any ongoing multipart uploads to prepare the bucket for deletion.
 node cleanupBuckets.js testbucket1,testbucket2
 ```
 
-# List objects that failed replication
+# List objects by replication status
 
-This script prints the list of objects that failed replication to stdout,
-following a comma-separated list of buckets. Run the command as
+This script prints the list of objects with a specific replication status to stdout,
+following a comma-separated list of buckets. By default, it lists objects with FAILED
+replication status to maintain backwards compatibility.
+
+## Usage
+
+```
+node listObjectsByReplicationStatus.js testbucket1,testbucket2
+```
+
+Or using the legacy script name (symlink):
 
 ```
-node listFailedObjects testbucket1,testbucket2
+node listFailedObjects.js testbucket1,testbucket2
 ```
 
+## Optional environment variables
+
+### REPLICATION_STATUS
+
+Comma-separated list of replication statuses to list. The recognized statuses are:
+
+* **NEW**: No replication status is attached to the object.
+* **PENDING**: The object replication status is PENDING.
+* **COMPLETED**: The object replication status is COMPLETED.
+* **FAILED**: The object replication status is FAILED (default).
+* **REPLICA**: The object replication status is REPLICA.
+
+The default behavior is to list objects with FAILED replication status (equivalent to `REPLICATION_STATUS=FAILED`).
+
+Examples:
+
+`REPLICATION_STATUS=PENDING`
+
+List objects that have a replication status of PENDING.
+
+`REPLICATION_STATUS=PENDING,FAILED`
+
+List objects that either have a replication status of PENDING or FAILED.
+
 # Verify existence of sproxyd keys
 
 This script verifies that :