When should test fixture scripts use the <<- heredoc style?

[EliahKagan]

The technical difference between the << and <<- here document operators is that, with <<-, leading tab characters are stripped. Its purpose is to permit here document contents to be indented, in scripts where tabs are used to do so.

The <<- operator is used in a number of gitoxide's test fixture scripts' here documents, even though the here documents' contents are not indented so it seems unnecessary. Running git grep -FnA2 '<<-EOF' reveals:

gix-dir/tests/fixtures/many.sh:327:  git update-index --index-info <<-EOF
gix-dir/tests/fixtures/many.sh-328-100644 $empty_oid	D/a
gix-dir/tests/fixtures/many.sh-329-100644 $empty_oid	d
--
gix-index/tests/fixtures/make_index/v2_icase_name_clashes.sh:13:git update-index --index-info <<-EOF
gix-index/tests/fixtures/make_index/v2_icase_name_clashes.sh-14-100644 $content_oid	FILE_X
gix-index/tests/fixtures/make_index/v2_icase_name_clashes.sh-15-100644 $content_oid	FILE_x
--
gix-worktree-state/tests/fixtures/make_dangerous_symlink.sh:14:git update-index --index-info <<-EOF
gix-worktree-state/tests/fixtures/make_dangerous_symlink.sh-15-100644 $empty_oid	A-dir/a
gix-worktree-state/tests/fixtures/make_dangerous_symlink.sh-16-100644 $empty_oid	A-file
--
gix-worktree-state/tests/fixtures/make_dangling_symlink.sh:7:  git update-index --index-info <<-EOF
gix-worktree-state/tests/fixtures/make_dangling_symlink.sh-8-120000 $target_oid	dangling
gix-worktree-state/tests/fixtures/make_dangling_symlink.sh-9-EOF
--
gix-worktree-state/tests/fixtures/make_ignorecase_collisions.sh:13:git update-index --index-info <<-EOF
gix-worktree-state/tests/fixtures/make_ignorecase_collisions.sh-14-100644 $content_oid	FILE_X
gix-worktree-state/tests/fixtures/make_ignorecase_collisions.sh-15-100644 $content_oid	FILE_x
--
gix/tests/fixtures/make_rev_spec_parse_repos.sh:104:  sed -e "s/|$//" >patch <<-EOF
gix/tests/fixtures/make_rev_spec_parse_repos.sh-105-diff --git a/frotz b/frotz
gix/tests/fixtures/make_rev_spec_parse_repos.sh-106-index 000000000..ffffff 100644

None of these have indented contents, much less the tab-intended contents needed for the <<- to make a difference.

However, one thing at least most of them do have is tab characters within their contents, just not as part of indentation.

Therefore, before I convert any of these to <<- as cleanup, and also before I assume I ought not to use the <<- heredoc operator when << would be sufficient, I wanted to check if this was intentional.

It definitely shouldn't affect the behavior of the shell that interprets the script. But I am curious if it is put there to prevent some text editors from overzealously converting those non-indenting internal tab characters into spaces.

I've been mostly using VS Code, which does not perform such a conversion even when I use the << heredoc operator, and even though I have it set up to indent with spaces. Furthermore, the tabs work fine when the scripts with << rather than <<- are run (as they should, since << never interprets tabs in any way other than literally). But I do not want to assume it isn't needed for some editor, or for some important configuration.

[Byron]

This is interesting!

Since I am not really aware of this heredoc format, it's unlikely I would have used it intentionally. Maybe it's part of the Git test-suite where parts have been extracted from initially. Most of the usages are either with git update-index or some sed script that I probably didn't write originally.

Thus, the answer might be in the Git test-suite - maybe the <<- around the sed line has a comment that would reveal if the - was added later and for a specific reason.
I most certainly have no reason for it and recommend removing - where it's not needed.
This might then also be a good commit for the Git mailing list - they are always accepting cleanups and fixes.

[Byron]

Great, I can't wait to see your name showing up when running ein t hours -p in git :).

Strangely enough, I submitted a fix that was accepted, yet my name isn't there. Oh well….

[EliahKagan]

Although Git does have some cases of <<- that could be <<, there are only 22 matches of <<-.?EOF\n+[^\n\t] (appearing in 18 files), out of about 800 here documents. So it's not a major problem, and I'm not sure a cleanup would necessarily be welcomed if not making other stylistic and clarity improvements to affected files.

Either way, I can go ahead and remove unnecessary uses of <<- from gitoxide's test fixture scripts or, if preferred, add leading tabs (though it doesn't look like indenting the contents is needed for readability in gitoxide's here documents, plus the general style of using four-space indentation outside here documents would make tab-based indentation in here documents, required for <<- to do any good, a bit confusing).

As for why you are not finding yourself in the output of ein t hours -p run in the git project's repository, I don't know why that would happen, since you appear listed when I run it:

C:\Users\ek\src\git [master ≡]> ein t hours -p | grep -FwA2 Thiel
 20:58:12 traverse commit graph done 73.8K commits in 0.68s (108.6K commits/s)
 20:58:12        estimate-hours Extracted and organized data from 73771 commits in 2.144ms (34408116 commits/s)
Sebastian Thiel <[email protected]>
1 commits found
total time spent: 2.00h (0.25 8h days, 0.00%)

That output agrees with the output of git shortlog, which includes:

Sebastian Thiel (1):
      mv: handle lstat() failure correctly

[Byron]

Ah, right, my terminal cut the output short, which makes sense as the 1 commit people are sorted to the beginning :D.

Yes, please go ahead with the changes here by removing the -.
And if the change is easy enough for you to create in Git itself and if you manage to submit it to the mailing list, I'd still encourage you: they can't do more than say no, and the value of them seeing something good (no matter how trivial) comes from gitoxide is totally worth the attempt to me. All the research you do towards correctness can one day also benefit them, so I think they should know your name, too :).

[EliahKagan]

Thanks. I should be able to do the cleanup for this in gitoxide fairly soon, but it might not be until tomorrow.

Related to this in Git, what I'm thinking of doing is to see if such cleanups, at this scale, are most often done with other style cleanup. Then I may be able to follow whatever practice around that seems to have been found most helpful in the past.

[EliahKagan]

I've opened #1435 for this. Sorry about the delay!