diff mbox series

[v2,1/2] t/README: document test_config

Message ID 20210515152721.885728-2-firminmartin24@gmail.com (mailing list archive)
State New
Headers show
Series document test_config & use it whenever possible | expand

Commit Message

Firmin Martin May 15, 2021, 3:27 p.m. UTC
test_config is used over one thousand times in the test suite, yet not
documented. Give it a place in the "Test harness library" section.

Thanks-to: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Firmin Martin <firminmartin24@gmail.com>
---
 t/README | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

Comments

Bagas Sanjaya May 16, 2021, 5:03 a.m. UTC | #1
On 15/05/21 22.27, Firmin Martin wrote:
>   
> + - test_config <config-option> [<value>]
> +
> +   Set the configuration option <config-option> to <value>, and unset it at the
> +   end of the current test. For a similar purpose, test_config_global for
> +   global configuration is also available. Note, however, that test_config_*
> +   must not be used in a subshell.
> +

 From the syntax above, when I omit <value>, default value for <config-option>
will be set, right? You forgot to mention it.

> +   Example:
> +
> +	test_config format.coverLetter auto
> +
> +   Is a concise way to write:
> +	test_when_finished "git config --unset format.coverLetter" &&
> +	git config format.coverLetter auto
> +
>   

The description said "set the config, then unset it". But the expanded version
said "unsetting the config is deferred to the end of test and set the config".

The documentation for test_when_finished said:

>    Prepend <script> to a list of commands to run to clean up
>    at the end of the current test.  If some clean-up command
>    fails, the test will not pass.

Is my interpretation above correct?

Oh yeah, maybe it's better to say:
"For example: <blah> have the same effect as <blah>."

Thanks.
Firmin Martin May 17, 2021, 7:44 a.m. UTC | #2
Hi Bagas,

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 15/05/21 22.27, Firmin Martin wrote:
>>   
>> + - test_config <config-option> [<value>]
>> +
>> +   Set the configuration option <config-option> to <value>, and unset it at the
>> +   end of the current test. For a similar purpose, test_config_global for
>> +   global configuration is also available. Note, however, that test_config_*
>> +   must not be used in a subshell.
>> +

>  From the syntax above, when I omit <value>, default value for <config-option>
> will be set, right? 
Good remark. I thought the same as you, but no, it will "git config
<config-option>" (query the value of <config-option>) and then "git
config --unset <config-option>" which is dangerous. Doing so is more
likely an error and should be forbidden, as in this case, it is
equivalent to test_unconfig <config-option>. Will reflect this in v3.
> You forgot to mention it.
I'll thus drop square brackets.

>> +   Example:
>> +
>> +	test_config format.coverLetter auto
>> +
>> +   Is a concise way to write:
>> +	test_when_finished "git config --unset format.coverLetter" &&
>> +	git config format.coverLetter auto
>> +
>>   
>
> The description said "set the config, then unset it". But the expanded version
> said "unsetting the config is deferred to the end of test and set the config".
>
> The documentation for test_when_finished said:
>
>>    Prepend <script> to a list of commands to run to clean up
>>    at the end of the current test.  If some clean-up command
>>    fails, the test will not pass.
>
> Is my interpretation above correct?
Yes.

> Oh yeah, maybe it's better to say:
> "For example: <blah> have the same effect as <blah>."
I agree, because the two lines have not exactly the same behaviour as
test_config. Will fix wording.

Thanks,

Firmin
diff mbox series

Patch

diff --git a/t/README b/t/README
index 8eb9e46b1d..aaf1c9cadc 100644
--- a/t/README
+++ b/t/README
@@ -1046,6 +1046,21 @@  library for your script to use.
    Abort the test script if either the value of the variable or the
    default are not valid bool values.
 
+ - test_config <config-option> [<value>]
+
+   Set the configuration option <config-option> to <value>, and unset it at the
+   end of the current test. For a similar purpose, test_config_global for
+   global configuration is also available. Note, however, that test_config_*
+   must not be used in a subshell.
+  
+   Example:
+
+	test_config format.coverLetter auto
+
+   Is a concise way to write:
+	test_when_finished "git config --unset format.coverLetter" &&
+	git config format.coverLetter auto
+
 
 Prerequisites
 -------------