Document that --refs parameters cannot start with a hyphen

[andry81]

Found beside another issue: #468

If use --refs as range parameter just like in the git filter-branch:

git-filter-repo-replace-text.sh:

function call()
{
  local IFS=$' \t'
  echo ">$*"
  "$@"
}

expressions_text="$1"

TEMP_OUTPUT_FILE=`mktemp -t git_filter_repo_update_file_text.XXXXXXXXXX`

# cleanup on return
trap "rm -rf \"$TEMP_OUTPUT_FILE\" 2> /dev/null; trap - RETURN" RETURN

call git-filter-repo-replace-text --replace-text "$TEMP_OUTPUT_FILE" "${@:2}"

git-filter-repo-replace-text "<p/>==></p>" --refs master --not t1^@

>git filter-repo --replace-text /tmp/git_filter_repo_update_file_text.wSOPH7Vu7j --refs master --not t1^@
git-filter-repo: error: unrecognized arguments: --not t1^@

I know it has to be a bit corrected:

git-filter-repo-replace-text.sh "<p/>==></p>" --refs master ^t1^@

But nevertheless --refs is not completely compatible with the git rev-list format.

[newren]

I was certain I had already documented that --refs doesn't take any hyphenated options (such as --not), but it appears I didn't mention that anywhere. Oops.

Not a bug, though, it's just a somewhat natural consequence of the fact that python's argparse is going to attempt to parse all the hyphenated options, and if I wanted to make it work like git, then I'd have to specially treat double dashes and just let all the arguments be positional. I don't want to go that route. Besides, filter-repo is about scripting and folks can use git-for-each ref and git-rev-parse if they really need to...though I suspect that most attempts to be clever with --refs are more likely just misues of the tool (as per your other ticket).

Anyway, thanks for pointing out that I forgot to document this. We should mention that the things passed to --refs cannot begin with a hyphen.

[andry81]

But this means that will be a challenge to convert git filter-branch into git filter-repo as a replacement. The git filter-branch uses generic git rev-list syntax, when you are not.

[newren]

But this means that will be a challenge to convert git filter-branch into git filter-repo as a replacement. The git filter-branch uses generic git rev-list syntax, when you are not.

git shortlog origin/next --branches --not origin/main

is equivalent to

git shortlog $(git rev-parse --symbolic origin/next --branches --not origin/main)

which is a pretty trivial conversion. If filter-repo was a command you used very frequently, I could understand possibly wanting to not need to do that conversion. However, since filter-branch and filter-repo are only supposed to be used once in a blue moon and only with special care, I don't think needing to convert like this is at all onerous. And if it discourages more people from using --refs, especially since that is often misused, all the better.