git - What is the difference between Repository.checkout() and Repository.checkout_head() in pygit2?

Question

When pulling and integrating changes from remote with pygit2, the last step is to checkout using Repository.checkout() or Repository.checkout_head(). Which to use?

Both of these take a checking out strategy as an argument. Now there are a couple of strategies for checking out viz GIT_CHECKOUT_SAFE, GIT_CHECKOUT_SAFE_CREATE, GIT_CHECKOUT_FORCE etc.
The problem I am facing is that even after checking out the index file is modified ie there are a couple of files in it that are staged.

r.repo.status()
{'README.md': 2}

When using the strategy GIT_CHECKOUT_FORCE the indexed is empty and the commits are also being stored.

When should GIT_CHECKOUT_FORCE strategy not be used?
Here is the step by step code of the process:
r.repo is Repository object. remo is the remote with name ssh-sansa

>>> r.repo.status()
{}
>>> z = remo.fetch()
>>> remoref = r.repo.lookup_reference('refs/remotes/ssh-sansa/master')
>>> rref = r.repo.lookup_reference(r.ref)
>>> r.ref
'refs/heads/master'
>>> remoref.target.hex
'23aac24f65c775d0524095d422133c63caf3826a'
>>> rref.target.hex
'29f5f99722e9c93a58ec085a55c6a4814c4adffb'
>>> rref.target=remoref.target.hex
>>> rref.target.hex
'23aac24f65c775d0524095d422133c63caf3826a'
>>> r.repo.status()
{'README.md': 2}
>>> r.repo.checkout_head(repo_.pygit2.GIT_CHECKOUT_SAFE_CREATE)
>>> r.repo.status()
{'README.md': 2}
>>> r.repo.checkout('HEAD',strategy=repo_.pygit2.GIT_CHECKOUT_SAFE_CREATE)
>>> r.repo.status()
{'README.md': 2}
>>> r.repo.checkout('HEAD',strategy=repo_.pygit2.GIT_CHECKOUT_FORCE)
>>> r.repo.status()
{}

Note: This is a follow up question to pulling and integrating changes using pygit2 and another question here

Answer 1

There is no difference. If you pass a refname of 'HEAD' to Repository.checkout(), it will call Repository.checkout_head().

As to why the file remains modified, it is because you've told the library not to overwrite changes. See the strategy docs for a description of what each strategy does. Specifically,

In between those are GIT_CHECKOUT_SAFE and GIT_CHECKOUT_SAFE_CREATE both of which only make modifications that will not lose changes.

As your file is modified, overwriting it would cause us to lose changes and hence it refuses to. If you want to overwrite it, then use FORCE or cause the file not to be in a modified state.