Add support for git restore

[LittleHaku]

It would be very nice to have the option of git restore with fuzzy find, since some times you modify a file and then decide that before it was better, so an option with git restore like grs would be very handy.

[sandr01d]

This sounds very similar to what we already provide with gcf (git checkout file). Could you please explain what grs would provide that gcf does not?

[carlfriedrich]

Ping @LittleHaku: can you answer the above question by @sandr01d? Otherwise I will close this issue within a few days.

[LittleHaku]

I see it as a compliment, where it would be a clearer approach, more explicit about what is going on using restore instead of checkout file. Also restore lets you restore to the index instead of HEAD.

So case you have a file that says Hello then you modify it and says Hello world, you add it (stage it) and modify it again to Hello world!, here restore would take it back to Hello world, checkout would take it back to HEAD, i.e., Hello.

[sandr01d]

Also restore lets you restore to the index instead of HEAD.

So case you have a file that says Hello then you modify it and says Hello world, you add it (stage it) and modify it again to Hello world!, here restore would take it back to Hello world, checkout would take it back to HEAD, i.e., Hello.

checkout also restores from the index and not HEAD. From the git checkout man page:

checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] ..., git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]

Overwrite the contents of the files that match the pathspec. When the <tree-ish> (most often a commit) is not given, overwrite working tree with the contents in the index. When the <tree-ish> is given, overwrite both the index and the working tree with the contents at the <tree-ish>.

AFAIK the functionality of checkout got split up into switch (git checkout <branch>) and restore (git checkout <pathspec>) with git 2.23, but those new commands serve the same purpose and behave the same as the corresponding functionality of checkout (see this).

gcf got implemented (0d34ff5) before git restore was introduced in git, which is why it is using checkout). I'm open to have a discussion on whether we should transition gcf to use restore (and gcb to use switch) instead of checkout, but I don't see any benefit of having a function for restore and checkout. Maybe it would also be worth adding additional aliases (gsw - git switch & grs - git restore) to these functions. Especially people that picked up git after the change are probably more used to the new commands.

[LittleHaku]

You are completely right about the equivalence. However, I think it still there is value in adding git restore.

First, future proofing, git explicitly recommends using the new git restore command. It is preferred to used both git restore and git switch over git checkout and thus, forgit should rather use them. They are also easier to understand and less prone to errors due to the separation of concerns.

Also, it is way easier to understand what git restore does over git checkout, plus newer users will learn the new git restore and git switch over git checkout as stated in many guides and documentation.

I myself use the new alternatives more since they are easier to remember, if I messed up a file I will just use restore, more often than I will like... I also use staged as pseudo-commit, I say pseudo since it is low-key a checkpoint that I use when something works but it's still not fully done.

Getting back to the main topic, rather than duplicating functionality forever, what about:

1. Keep gcf for backward compatibility
2. Add grs using git restore and gsw to git switch
3. Eventually deprecate gcf with a notice pointing to grs and gsw

Lastly, let me link you this discussion that I found interesting: https://news.ycombinator.com/item?id=42649858

Thank you for your time!

[carlfriedrich]

@LittleHaku Thanks for pointing that out. Really interesting! I actually did not know about this redudancy in git commands, yet, and must confess I never actually used git switch or git restore to this day. This thread might have been a kickoff to try using those commands instead in order to get to know the alternative workflows.

In this light, however, I total agree with you that it's a good idea for forgit to have counterparts for these newer git commands. Especially since forgit mainly is a more user-friendly interface to using git. I have not thought through this completely, yet, but at first glance your three steps make sense to me. I would add that gcb probably also should be deprecated in favor of gsw then.

[LittleHaku]

@carlfriedrich I think it makes sense to deprecate gcb too.

@sandr01d What do you think about it?

If I can I would like to try and help, I have never participated in a big open source software.

[sandr01d]

I agree, deprecating gcb and gcf in favor of gsw and grs makes sense and so do the steps you proposed for transitioning. We might want to start print a deprecation warning from the old functions one or two releases before we finally remove them. I wouldn't expect most people to read our release notes...

If I can I would like to try and help, I have never participated in a big open source software.

Sure, if you want you are more than welcome to open up PRs for the new functions. The process should be pretty straight forward as you can reuse most of the code from the existing ones. Here are a few pointers on what needs to be done:

• duplicate the respective functions for checkout file and checkout branch and replace everything checkout related with restore and switch respectively, e.g. for checkout file this would be this section of the code:

  forgit/bin/git-forgit

  Lines 835 to 862 in 5d4d612

  	_forgit_checkout_file_preview() {
  	git diff --color=always -- "$1" | _forgit_pager diff
  	}
  	_forgit_git_checkout_file() {
  	_forgit_checkout_file_git_opts=()
  	_forgit_parse_array _forgit_checkout_file_git_opts "$FORGIT_CHECKOUT_FILE_GIT_OPTS"
  	git checkout "${_forgit_checkout_file_git_opts[@]}" "$@"
  	}
  	# git checkout-file selector
  	_forgit_checkout_file() {
  	_forgit_inside_work_tree || return 1
  	local files opts
  	_forgit_contains_non_flags "$@" && { _forgit_git_checkout_file "$@"; return $?; }
  	opts="
  	$FORGIT_FZF_DEFAULT_OPTS
  	-m -0
  	--preview=\"$FORGIT checkout_file_preview {}\"
  	$FORGIT_CHECKOUT_FILE_FZF_OPTS
  	"
  	files=()
  	while IFS='' read -r file; do
  	files+=("$file")
  	done < <(_forgit_list_files --modified |
  	FZF_DEFAULT_OPTS="$opts" fzf)
  	[[ "${#files[@]}" -gt 0 ]] && _forgit_git_checkout_file "$@" "${files[@]}"
  	}

• Add shell functions and aliases in https://github.com/wfxr/forgit/blob/main/forgit.plugin.zsh
• To test the new functions you can now simply source forgit.plugin.zsh and they should become available
• Add completions for the new functions for zsh, bash and fish in the respective files at https://github.com/wfxr/forgit/tree/main/completions. The syntax for completion functions for bash and zsh is a bit weird if you haven't worked with it before. The main thing you should know is that we essentially "forward" gits completion functions to our commands. You can use the existing completion functions as guide.
• Add the new functions to the README and add in a deprecation warning for the old ones.

I think it would be best to open separate PRs for each of the functions. Should you have any questions don't hesitate to ask in this issue or in the PR once you've opened it.

@carlfriedrich just as a note, I think it would be a good idea to add something like the above to the "Contributing" section once we add it.

[LittleHaku]

Got it, @sandr01d I will try to get to this ASAP. Thanks for the guidance!