Git Extension API - Deprecating ApiRepositoryState.refs

[lszomoru]

👋🏻 Extension Authors,

Over the last several milestones we have been working on performance improvements to the vscode.git extension and as part of that effort we have focused on the code that is executed after every git operation, and updates the "state" of the repository. The state is used internally by the vscode.git extension, as well as other extensions that depend on the vscode.git extension and access it the git extension API.

One operation that gets executed to update the state spawns git.exe to refresh the list of local refs, which can vary depending on the size of the repository. We are moving to a model where rather than constantly keeping the list of refs up to date, we will enable extension authors to query for the list of local refs when the information is needed.

Here is the current execution plan of the git extension API deprecation:

• Add ApiRepository.getRefs(query: RefQuery, cancellationToken?: CancellationToken): Promise<Ref[]>
• Update the vscode.git extension to use the getRefs() method
• Update 1st party extensions to use the getRefs() method
• In VS Code 1.76:
  • Update ApiRepositoryState.refs to return empty array, and log a deprecation notice to the console
  • Delete the code that keeps the list of refs updated

🔈 If you own an extension that depends on the vscode.git extension API, please review your extension and see if you are using the ApiRepositoryState.refs property. If so, please update your code to use ApiRepository.getRefs() instead and query for the list of refs when needed.

In case you have any questions about the newly added extension API please let me know.

Happy Coding.

[davila7]

Thanks @lszomoru

Where can I find the documentation for vscode.git ?

[lszomoru]

There is some very basic documentation here.
Is there something particular that you are looking for? Thanks!

[davila7]

thanks!
I am trying to get some details.
For example, I would like to get all the code out of the "commit".

[lszomoru]

Could you please elaborate on what you mean by "get all the code out of the commit"?

[davila7]

Yes, for example.

If I made a change, I would like to get the changes before committing, as seen in the image.

[lszomoru]

@davila7, please try the various diff* methods in ApiRepository. If you have further questions or concerns about the git extension API I would suggest that we move that to a separate discussion so that we can keep this one focused on the deprecation effort. Thank you!

[lszomoru]

📣 The code changes described in the initial post are now available in Insiders 1.76.

[nbransby]

how does this affect RepositoryState.onDidChange, presumably if ApiRepositoryState.refs is always an empty array then we won't be notified when they change, for example post fetch.

Is there another way to get notified on this now?

[lszomoru]

The RepositoryState.onDidChange event always fires when the state of the repository changes and it was not scoped to the refs. Just like in the past you would listen to the RepositoryState.onDidChange event and then call ApiRepositoryState.refs you now need to continue to listen to the same event and call ApiRepository.getRefs().

[nbransby]

Right but doesn't that negate the optimization you made in the first place if all extensions have to call ApiRepository.getRefs() everytime they receive the RepositoryState.onDidChange event? We had the following optimization to prevent performing additional operations on receiving RepositoryState.onDidChange because we found it was called A LOT:

        var state = `${this.repo.state.HEAD?.name}:${this.repo.state.HEAD?.commit}`;
        state = `${state}+${this.repo.state.HEAD?.upstream?.name}:${this.repo.state.HEAD?.upstream?.commit}`;
        state = `${state}+${this.repo.state.refs.map(it => `${it.name}:${it.commit}:${it.type}`).join()}`;
        state = `${state}+${this.repo.state.indexChanges.map(it => `${it.originalUri}:${it.renameUri}:${it.status}`).join()}`;
        return this.repo.state.onDidChange(() => {
            var newState = `${this.repo.state.HEAD?.name}:${this.repo.state.HEAD?.commit}`;
            newState = `${newState}+${this.repo.state.HEAD?.upstream?.name}:${this.repo.state.HEAD?.upstream?.commit}`;
            newState = `${newState}+${this.repo.state.refs.map(it => `${it.name}:${it.commit}:${it.type}`).join()}`;
            newState = `${newState}+${this.repo.state.indexChanges.map(it => `${it.originalUri}:${it.renameUri}:${it.status}`).join()}`;
            if(newState != state) {
                state = newState;
                onChange();
            }
        });

Obviously now this solution will not work as the ref changes won't be detected. If the Git Extension knows what has possibly changed when firing the event it would be useful if it could pass that information in the event, even just a boolean to know if its the refs that have changed or not.

[lszomoru]

To support some of the functionality of the Source Control Graph, we have added back the code to get the list of references. Since the API for the Source Control Graph is still in a proposed state I did not want to re-expose the refs just yet but if the API will be finalized in its current form I will do so.