[PATCH v2 0/2] improve documentation around git-update-ref

From: Karthik Nayak <karthik.188@gmail.com>

This patch series was derived out of the discussion [1] around my other patch series to add symref support for `git-update-ref(1)` [2].

The aim of these patches is to improve clarity around OIDs in the documentation. This makes it easier to draw parallels between regular ref updates and symref updates. The symref patch series will be rebased on top of this in the upcoming version.

Changes in v2:
- Fixed broken tests due to changes in update-ref.c

Range diff against v1:
1:  5a315a0aa0 ! 1:  f5cc3738ee update-ref: use {old,new}-oid instead of {old,new}value
    @@ builtin/update-ref.c: static void parse_cmd_delete(struct ref_transaction *trans
      		have_old = 1;
      	}
      
    +
    + ## t/t1400-update-ref.sh ##
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin fails create with no ref' '
    + test_expect_success 'stdin fails create with no new value' '
    + 	echo "create $a" >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: create $a: missing <newvalue>" err
    ++	grep "fatal: create $a: missing <new-oid>" err
    + '
    + 
    + test_expect_success 'stdin fails create with too many arguments' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin fails update with no ref' '
    + test_expect_success 'stdin fails update with no new value' '
    + 	echo "update $a" >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: update $a: missing <newvalue>" err
    ++	grep "fatal: update $a: missing <new-oid>" err
    + '
    + 
    + test_expect_success 'stdin fails update with too many arguments' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin update ref fails with wrong old value' '
    + test_expect_success 'stdin update ref fails with bad old value' '
    + 	echo "update $c $m does-not-exist" >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err &&
    ++	grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    + test_expect_success 'stdin create ref fails with bad new value' '
    + 	echo "create $c does-not-exist" >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: create $c: invalid <newvalue>: does-not-exist" err &&
    ++	grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    + test_expect_success 'stdin create ref fails with zero new value' '
    + 	echo "create $c " >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: create $c: zero <newvalue>" err &&
    ++	grep "fatal: create $c: zero <new-oid>" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin delete ref fails with wrong old value' '
    + test_expect_success 'stdin delete ref fails with zero old value' '
    + 	echo "delete $a " >stdin &&
    + 	test_must_fail git update-ref --stdin <stdin 2>err &&
    +-	grep "fatal: delete $a: zero <oldvalue>" err &&
    ++	grep "fatal: delete $a: zero <old-oid>" err &&
    + 	git rev-parse $m >expect &&
    + 	git rev-parse $a >actual &&
    + 	test_cmp expect actual
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails create with no ref' '
    + test_expect_success 'stdin -z fails create with no new value' '
    + 	printf $F "create $a" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: create $a: unexpected end of input when reading <newvalue>" err
    ++	grep "fatal: create $a: unexpected end of input when reading <new-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z fails create with too many arguments' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails update with no ref' '
    + test_expect_success 'stdin -z fails update with too few args' '
    + 	printf $F "update $a" "$m" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err
    ++	grep "fatal: update $a: unexpected end of input when reading <old-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z emits warning with empty new value' '
    + 	git update-ref $a $m &&
    + 	printf $F "update $a" "" "" >stdin &&
    + 	git update-ref -z --stdin <stdin 2>err &&
    +-	grep "warning: update $a: missing <newvalue>, treating as zero" err &&
    ++	grep "warning: update $a: missing <new-oid>, treating as zero" err &&
    + 	test_must_fail git rev-parse --verify -q $a
    + '
    + 
    + test_expect_success 'stdin -z fails update with no new value' '
    + 	printf $F "update $a" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: update $a: unexpected end of input when reading <newvalue>" err
    ++	grep "fatal: update $a: unexpected end of input when reading <new-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z fails update with no old value' '
    + 	printf $F "update $a" "$m" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: update $a: unexpected end of input when reading <oldvalue>" err
    ++	grep "fatal: update $a: unexpected end of input when reading <old-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z fails update with too many arguments' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails delete with no ref' '
    + test_expect_success 'stdin -z fails delete with no old value' '
    + 	printf $F "delete $a" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: delete $a: unexpected end of input when reading <oldvalue>" err
    ++	grep "fatal: delete $a: unexpected end of input when reading <old-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z fails delete with too many arguments' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z fails verify with too many arguments' '
    + test_expect_success 'stdin -z fails verify with no old value' '
    + 	printf $F "verify $a" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: verify $a: unexpected end of input when reading <oldvalue>" err
    ++	grep "fatal: verify $a: unexpected end of input when reading <old-oid>" err
    + '
    + 
    + test_expect_success 'stdin -z fails option with unknown name' '
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z update ref fails with wrong old value' '
    + test_expect_success 'stdin -z update ref fails with bad old value' '
    + 	printf $F "update $c" "$m" "does-not-exist" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: update $c: invalid <oldvalue>: does-not-exist" err &&
    ++	grep "fatal: update $c: invalid <old-oid>: does-not-exist" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z create ref fails with bad new value' '
    + 	git update-ref -d "$c" &&
    + 	printf $F "create $c" "does-not-exist" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: create $c: invalid <newvalue>: does-not-exist" err &&
    ++	grep "fatal: create $c: invalid <new-oid>: does-not-exist" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    + test_expect_success 'stdin -z create ref fails with empty new value' '
    + 	printf $F "create $c" "" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: create $c: missing <newvalue>" err &&
    ++	grep "fatal: create $c: missing <new-oid>" err &&
    + 	test_must_fail git rev-parse --verify -q $c
    + '
    + 
    +@@ t/t1400-update-ref.sh: test_expect_success 'stdin -z delete ref fails with wrong old value' '
    + test_expect_success 'stdin -z delete ref fails with zero old value' '
    + 	printf $F "delete $a" "$Z" >stdin &&
    + 	test_must_fail git update-ref -z --stdin <stdin 2>err &&
    +-	grep "fatal: delete $a: zero <oldvalue>" err &&
    ++	grep "fatal: delete $a: zero <old-oid>" err &&
    + 	git rev-parse $m >expect &&
    + 	git rev-parse $a >actual &&
    + 	test_cmp expect actual
2:  17950e0693 = 2:  972faccb4a githooks: use {old,new}-oid instead of {old,new}-value

[1]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#m7bb4d1f44b656d7cfb73ed3220b990aa6d1ac247 [2]: https://public-inbox.org/git/20240330224623.579457-1-knayak@gitlab.com/T/#t

Karthik Nayak (2):
  update-ref: use {old,new}-oid instead of {old,new}value
  githooks: use {old,new}-oid instead of {old,new}-value

 Documentation/git-update-ref.txt | 58 ++++++++++++++++----------------
 Documentation/githooks.txt       | 16 ++++-----
 builtin/update-ref.c             | 26 +++++++-------
 t/t1400-update-ref.sh            | 34 +++++++++----------
 4 files changed, 67 insertions(+), 67 deletions(-)