fix: do not use git set-branches if the target branch is not currently available in the repository

[tromai]

Closes #486

Bug description

This bug happened because of the way branch check out is handling in this method.

At the moment, the process Macaron in which Macaron tries to checkout the correct branch and commit for the analysis is as follows:

• The branch to checkout is either the value provided by the user (via --branch in the CLI) or the default branch of the repository (implementation):

  • We are using git rev-parse --abbrev-ref origin/HEAD to obtain the value origin/<default_branch_name> (references).

• Macaron try to check out that branch (implementation here)..

  • The way we check if a given branch exists in the repository:
    • res_branch in [os.path.basename(ref.name) for ref in org_remote.refs]
    • The refs in org_remote instance would return git.RemoteReference instances (according to gitpython documentation).
    • The documentation for git remote references can be seen here.
    • Therefore, each git.RemoteReference can be considered a reference to the latest commit of a remote branch (from the last time we communicate with remote). Therefore, org_remote.refs will return an iterator of remote references that this local repository currently have (which mean that it could be missing any new remote branches, etc.).
    • I have manually check in a shallow clone, a call to org_remote.refs does not return all available remote branches. It only contains: 1. refs/remotes/origin/<branch_name> which point to the branch which we shallow clone (if no branch is provided e.g. git clone --depth=1 <url>), this will be refs/remotes/origin/<default_branch>. 2. if it's a shallow clone of the default branch, there will be also a refs/remotes/origin/HEAD.

• If Macaron cannot find the target branch from org_remote.refs, Macaron will try to setup a local branch that track that branch from origin remote (implementation here).

  • The full command is: git remote set-branches --add origin '<target_branch>' (references) What this command do is that it setup the branch list to track a branch <target_branch> from the remote. The --add will make sure that we only add the new tracked branch into the list of tracked branches. The next time we fetch, git will also try to fetch this branch from the remote repository. The reason I did it this way is to make sure that we only need to fetch the branch that we are interested in when working with shallow clones.

  • This is the command that causes the bug in Repository checkout fails in some cases #486:

    • This command this will update the .git/config file in the target repository with <target_branch>. Therefore, if the branch doesn't exist, subsequent fetching/pulling will always fail because git will try to ask the remote for this non-exist branch and return error everytime.
    • The second issue: there is a fetching operation happened here without checking if offline_mode is set or not.
    • The third issue is that we don't have a good way to revert the effect of set-branches (https://stackoverflow.com/questions/47726087/undo-set-branches-on-git-remote). Overall, it's not a good idea to perform git operations that alter .git/config.

Solution.

To resolve this bug, I simplify the logic for checkout branch and commit for a target repository with the following goals:

• Remove any conditional logic for handling shallow-clone repositories:
  • The usage of git remote set-branches --add origin '<target_branch>'
  • Unshallow when trying to pull from latest (note here).
• Make sure that the only online operations included in the check_out_repo_target method are:
  • git fetch: happen before checkout branch.
  • git pull --ff-only before checkout a specific commit.

If the checkout operation fails for either branch or commit, we return errors.