🚨 Special Instructions 🚨

If this is your first time using the sparse index, then you will need to run the following command after installing:

git sparse-checkout reapply

If you run into an issue using this release, then please follow these instructions:

1. Run scalar diagnose and note where it places a .zip file.
2. Run git sparse-checkout reapply and try your steps again.
3. Create an issue detailing your issue and if you had success with step 2.
4. Send your .zip file to git-fundamentals@github.com along with a link to your issue.

Major Changes

Includes Git 2.34.0.

The sparse index is now enabled by default. Users using cone-mode
sparse-checkout should see significant performance benefits for the
following commands:

• git status
• git commit
• git add
• git checkout
• git reset
• git diff
• git sparse-checkout
• git merge
• git rebase
• git cherry-pick
• git stash
• git fetch
• git pull

Some other commands might have performance regressions since they are not
integrated with the sparse index. If you have any performance issues with
this release, then please create an issue detailing your scenario.
Please re-run your command with GIT_TRACE2_PERF=1 and supply those logs
to assist a quick response.

Pull Requests since v2.33.0.vfs.0.3

• #454: README: fix winget instructions
• #455: fetch/pull: use the sparse index
• #458: Remove Ubuntu 18.04 deployments
• #459: Use wingetcreate to publish Windows releases
• #463: fixup! scalar register: set recommended config settings
• #464: Bump update-winget version
• #465: sparse-checkout: avoid crash when switching between cone and non-cone
• #468: maintenance: delete stale lock files, fix loose-objects task

Special Thanks

We'd like to give an extra shout out to the participants in our internal and public bug bashes for the 2.34.0 release. Thank you for finding bugs, validating features, and overall being an integral part of this release!

• @marcelais 🎉
• @talum 🙌
• @ldennington 🥳
• @dscho ✨

See #460 for the rebase onto v2.34.0-rc0.windows.1.

Includes Git 2.34.0-rc0.

(Remaining release notes TBD.)

Major Changes

This mid-cycle release fixes a performance regression where Git would parse the list of environment variables too many times. This was fixed in #451.

There are several other changes since v2.33.0.vfs.0.0, many of which involve the sparse index, which remains disabled by default in this release (see #452). Other improvements fix issues with building and running the installers.

Due to updates in how we build installers on macOS, we now require macOS 10.15 or later.

Pull Requests

Included in v2.33.0.vfs.0.1 pre-release:

• #409: Fix cURL linking issue in Mac installer from tag-to-release build
• #412: Update Ubuntu/Debian install instructions
• #413: build-git-installers: Ubuntu bugfix, Windows features
• #410: Sparse index: latest integrations
• #414: Make sparse index the default (Reverted in #452)
• #416: Anticipate future VS versions in the release workflow
• #422: Remove Ubuntu 16.04 from test matrix
• #421: Sparse index: integrate with the sparse-checkout builtin
• #415: scalar: enable untracked cache unconditionally
• #417: Sparse index: git reset
• #419: diff: enable and test the sparse index

Included in v2.33.0.vfs.0.2 pre-release:

• #423: Sparse index: integrate with git update-index
• #425: Sparse index: add more performance tests
• #424: Sparse index: checkout-index
• #427: Upgrade update-winget action to v1.4
• #426: Sprase index: integrate with read-tree
• #428: Sparse index: integrate with git stash
• #429: Improve next_cache_entry cache traversal performance
• #430: Sparse index: integrate with clean and stash -u
• #432: sequencer: avoid progress when stderr is redirected
• #433: REmove sparse index expansions from untracked file stashes
• #431: blame: enable and test the sparse index
• #434: Integrate git update-microsoft-git with apt-get
• #436: Merge Git for Windows v2.33.0(2)
• #437: Replace pre-V4 of FSMonitor with V4 using GFW experimental commits
• #438: .github: continue pestering until user upgrades
• #439: sparse index: fix use-after-free bug in cache_tree_verify()
• #442: Fix installer builds
• #444: Sparse Index: upstream updates to git reset
• #447: ci(windows): avoid using external gpg by mistake
• #448: FSMonitor: deepening a directory causes confusing events
• #445: .github: replace recently seen logic

New only to this version:

• #451: Initialize virtual filesystem settings only once
• #452: disable sparse index

This pre-release is an early release that includes new integrations with the sparse index and a new version of FSMonitor.

For those participating in the Bug Bash, this is the version to use!

Installation Instructions

Windows

Download and install the .exe installer.

macOS

Download the .pkg installer, right-click and select "Open".

Debian-based Linux

Download the .deb installer and install with dpkg -i microsoft-git_2.33.0.vfs.0.2.deb.

Other Linux Distributions

Clone the repository, check out this tag, and build from source.

git clone https://github.com/microsoft/git
cd git
git checkout v2.33.0.vfs.0.2
<install dependencies>
make -j12 prefix=/usr/local
sudo make -j12 prefix=/usr/local install

Major Updates (since v2.33.0.vfs.0.1 prerelease)

• New sparse index command integrations:
  • git update-index
  • git checkout-index
  • git stash
  • git blame
  • git clean
  • git read-tree
• FSMonitor V4

Pull Requests

• #423: Sparse index: integrate with git update-index
• #425: Sparse index: add more performance tests
• #424: Sparse index: checkout-index
• #427: Upgrade update-winget action to v1.4
• #426: Sparse index: integrate with read-tree
• #428: Sparse index: integrate with git stash
• #429: Improve next_cache_entry cache traversal performance
• #430: Sparse index: integrate with clean and stash -u
• #432: sequencer: avoid progress when stderr is redirected
• #433: Remove sparse index expansions from untracked file stashes
• #431: blame: enable and test the sparse index
• #434: Integrate git update-microsoft-git with apt-get
• #436: Merge Git for Windows v2.33.0(2)
• #437: Replace pre-V4 of FSMonitor with V4 using GFW experimental commits
• #438: .github: continue pestering until user upgrades
• #439: sparse index: fix use-after-free bug in cache_tree_verify()
• #444: Sparse Index: upstream updates to git reset
• #447: ci(windows): avoid using external gpg by mistake
• #442: Fix installer builds
• #448: FSMonitor: deepening a directory causes confusing events (Take 2)
• #445: .github: replace recently seen logic

This pre-release is an early release that includes several integrations with the sparse index.

Major Updates

• The sparse index is enabled by default.
• The untracked cache is enabled by default on Windows. (It was already enabled by default on other platforms.)
• The sparse index now integrates with these commands:
  • git add
  • git checkout
  • git cherry-pick
  • git commit
  • git diff
  • git merge
  • git rebase
  • git reset
  • git sparse-checkout
  • git status

Pull Requests

• #409: Fix cURL linking issue.
• #410: Sparse Index: latest integrations
• #414: Make sparse index the default
• #416: Anticipate future VS versions in the release workflow
• #422: Remove Ubuntu 16.04 from test matrix
• #421: Sparse index: integrate with the sparse-checkout builtin
• #415: scalar: enable untracked cache unconditionally
• #417: Sparse Index: git reset
• #419: diff: enable and test the sparse index

Major Updates

• This includes Git for Windows 2.33.0.
• The merge strategy default is changed from recursive to ort which should present significant performance improvements for commands such as git merge, git rebase, and git cherry-pick. Huge thanks to external contributor @newren for creating this new merge strategy!
• Several small improvements to the Scalar CLI are included.
• Our process for creating releases and making them available via winget, brew, and apt-get continues to improve.

Pull Requests

• #386: Add release-apt-get workflow
• #392: add: allow adding sparse entries when virtual
• #393: Add instructions for apt-get install to README
• #394: scalar clone: display the cache server URL that is used (if any)
• #395: sparse-index: fix crash in status
• #398: Fix some whitespace issues
• #399: Implement workflow to create GitHub release with attached git installers
• #402: Handle Scalar enlistments without src directory
• #403: Add --include-pdbs to make_installers_from_mingw_w64_git()
• #404: Make 'ort' the default merge strategy

This release includes an early version of the sparse index feature. This feature significantly reduces the size of the .git/index file when using cone-mode sparse-checkout patterns, making integrated Git commands much faster. These commands have been integrated with the sparse index in this version:

• git status
• git commit
• git checkout
• git add

These integrations are considered safe to use in production use. The reason this release is experimental is because the sparse index adds some overhead to commands that have not been integrated with the feature. Thus, commands such as git diff, git merge, and git rebase have additional cost to translate from the sparse index into a full one before performing operations on the index. We plan to integrate these commands (among others) in a future release.

This release enables the sparse index by default. New clones will automatically start with a sparse index.

To update an existing clone to have a sparse index, run git sparse-checkout reapply.

If you previously disabled the sparse index, run git sparse-checkout init --cone --sparse-index to reenable it.

Update to Experimental Release

Our first experimental release of the sparse index feature (v2.32.0.vfs.0.99.exp) had two bugs that have since been resolved. These were due to gaps in our test suites that have been resolved. Here are the important points of how these bugs have been resolved:

• There was a bug when expanding a sparse index to a full one in a way that affected the untracked cache. This was causing a crash in git status. While we fixed the bug (see #395) we also identified why the users were hit this code path at all during git status. When changing a sparse-checkout definition to remove a directory that was previously in the cone, Git only removed the tracked files in that directory, not the ignored ones. This means that users who had build artifacts in those directories would now see them as ignored, untracked files. To discover this was the case, git status would expand the sparse index to discover that they were indeed untracked. These build artifacts did not exist in our testing. We modified git sparse-checkout set to remove directories that go out of scope, including all contained ignored files. See #396, where a call to git clean -dfx -- <dir1> <dir2> ... performs this deletion.

• There was an unrelated error during git checkout that occurred rarely, but only when the sparse-checkout cone contained paths multiple levels deep and certain files changed triggering a code path that had a bug. This is resolved as part of #396 (see 2d3b5b4 for this specific fix).

Our second experimental release had a bug in its auto-upgrader that would look for new versions from git-for-windows/git instead of microsoft/git. This is fixed in this version.

Troubleshooting

If you see a problem with this feature, then please use these steps:

1. Run scalar diagnose.
2. Attach the resulting .zip file in an email to git-client@github.com.
3. Disable the sparse index with git sparse-checkout init --cone --no-sparse-index.

If you send such a report to us, then we will examine it with high priority to ensure you are unblocked.

Pull Requests since v2.32.0.vfs.0.3

• #374: [Sparse Index] Integrate with git status
• #361: [Sparse Index] Integrate with git commit and git checkout
• #364: [Sparse Index] Integrate git add with sparse-index
• #388: [Sparse Index] enable index.sparse by default
• #386: Add release-apt-get workflow
• #392: add: allow adding sparse entries when virtual
• #393: Add instructions for apt-get install to README
• #394: scalar clone: show cache server url
• #395: [Sparse Index] Fix crash in status
• #396: [Sparse Index] Delete ignored files outside of cone

This release includes an early version of the sparse index feature. This feature significantly reduces the size of the .git/index file when using cone-mode sparse-checkout patterns, making integrated Git commands much faster. These commands have been integrated with the sparse index in this version:

• git status
• git commit
• git checkout
• git add

These integrations are considered safe to use in production use. The reason this release is experimental is because the sparse index adds some overhead to commands that have not been integrated with the feature. Thus, commands such as git diff, git merge, and git rebase have additional cost to translate from the sparse index into a full one before performing operations on the index. We plan to integrate these commands (among others) in a future release.

This release enables the sparse index by default. New clones will automatically start with a sparse index.

To update an existing clone to have a sparse index, run git sparse-checkout reapply.

If you previously disabled the sparse index, run git sparse-checkout init --cone --sparse-index to reenable it.

Update to Experimental Release

Our first experimental release of the sparse index feature (v2.32.0.vfs.0.99.exp) had two bugs that have since been resolved. These were due to gaps in our test suites that have been resolved. Here are the important points of how these bugs have been resolved:

• There was a bug when expanding a sparse index to a full one in a way that affected the untracked cache. This was causing a crash in git status. While we fixed the bug (see #395) we also identified why the users were hit this code path at all during git status. When changing a sparse-checkout definition to remove a directory that was previously in the cone, Git only removed the tracked files in that directory, not the ignored ones. This means that users who had build artifacts in those directories would now see them as ignored, untracked files. To discover this was the case, git status would expand the sparse index to discover that they were indeed untracked. These build artifacts did not exist in our testing. We modified git sparse-checkout set to remove directories that go out of scope, including all contained ignored files. See #396, where a call to git clean -dfx -- <dir1> <dir2> ... performs this deletion.

• There was an unrelated error during git checkout that occurred rarely, but only when the sparse-checkout cone contained paths multiple levels deep and certain files changed triggering a code path that had a bug. This is resolved as part of #396 (see 2d3b5b4 for this specific fix).

Troubleshooting

If you see a problem with this feature, then please use these steps:

1. Run scalar diagnose.
2. Attach the resulting .zip file in an email to git-client@github.com.
3. Disable the sparse index with git sparse-checkout init --cone --no-sparse-index.

If you send such a report to us, then we will examine it with high priority to ensure you are unblocked.

Pull Requests since v2.32.0.vfs.0.3

• #374: [Sparse Index] Integrate with git status
• #361: [Sparse Index] Integrate with git commit and git checkout
• #364: [Sparse Index] Integrate git add with sparse-index
• #388: [Sparse Index] enable index.sparse by default
• #386: Add release-apt-get workflow
• #392: add: allow adding sparse entries when virtual
• #393: Add instructions for apt-get install to README
• #394: scalar clone: show cache server url
• #395: [Sparse Index] Fix crash in status
• #396: [Sparse Index] Delete ignored files outside of cone

This version includes the Scalar CLI!

In this version, we have completed porting all Scalar features into the microsoft/git fork, and many of the features are also in the core git/git project:

1. Background maintenance is in git/git.
2. FS Monitor is in microsoft/git and git-for-windows/git with a git/git version under review.
3. The GVFS Protocol (i.e. partial clone for Azure Repos) is built into microsoft/git via the git-gvfs-helper executable.
4. The Scalar CLI for creating and managing enlistments is now in microsoft/git.

The Scalar CLI documentation is available in this repository, and closely matches the functionality documented in microsoft/scalar.

Users should not notice any behavior differences between Scalar.NET and this new version, since this does not affect your day-to-day use of Git commands. Any issues are likely to happen in commands such as scalar clone or scalar register or during the installation itself.

Instructions for Windows Users

The Windows installer will uninstall Scalar.NET, if it exists, and update existing enlistments to be registered with this new version. If in doubt, run scalar list before and after upgrading to ensure the list is correct. If any enlistments are missing, then run scalar register . in the working directory of an enlistment you want registered.

Instructions for macOS Users

Warning: The macOS installer will not uninstall the existing Scalar.NET installation.

Before uninstalling the .NET version, run scalar list and store that list of enlistments in a file.

If you had Scalar.NET installed via HomeBrew, then you can use this command:

brew uninstall --cask scalar-azrepos

If you installed in another way, then run this script to uninstall the .NET version:

/usr/local/bin/uninstall_scalar.sh

After running the macOS installer, you will need to run scalar register . in your existing enlistments to ensure they are tracked by background maintenance and other changes in future versions. You can also run scalar register <path> for each <path> that was previously output by scalar list.

Instructions for Linux Users

The Linux installer will not uninstall the existing Scalar.NET installation, but it will replace the location of the scalar executable on the PATH. There is no established uninstall mechanism, but Scalar.NET can be removed via sudo rm -rf /usr/local/lib/scalar/.

After running the Linux installer (or compiling and installing from source), you will need to run scalar register . in your existing enlistments to ensure they are tracked by background maintenance and other changes in future versions.

Pull Requests since v2.32.0.vfs.0.2

• #390: Fix whitespace errors
• #387: Fix winget manifest tag formatting
• #385: Redo fixup for fsmonitor_last_update
• #380: Update winget manifest
• #379: vfs: disable the built-in FS Monitor

This version includes the Scalar CLI!

In this version, we have completed porting all Scalar features into the microsoft/git fork, and many of the features are also in the core git/git project:

1. Background maintenance is in git/git.
2. FS Monitor is in microsoft/git and git-for-windows/git with a git/git version under review.
3. The GVFS Protocol (i.e. partial clone for Azure Repos) is built into microsoft/git via the git-gvfs-helper executable.
4. The Scalar CLI for creating and managing enlistments is now in microsoft/git.

The Scalar CLI documentation is available in this repository, and closely matches the functionality documented in microsoft/scalar.

Users should not notice any behavior differences between Scalar.NET and this new version, since this does not affect your day-to-day use of Git commands. Any issues are likely to happen in commands such as scalar clone or scalar register or during the installation itself.

Instructions for Windows Users

The Windows installer will uninstall Scalar.NET, if it exists, and update existing enlistments to be registered with this new version. If in doubt, run scalar list before and after upgrading to ensure the list is correct. If any enlistments are missing, then run scalar register . in the working directory of an enlistment you want registered.

Instructions for macOS Users

Warning: The macOS installer will not uninstall the existing Scalar.NET installation.

Before uninstalling the .NET version, run scalar list and store that list of enlistments in a file.

If you had Scalar.NET installed via HomeBrew, then you can use this command:

brew uninstall --cask scalar-azrepos

If you installed in another way, then run this script to uninstall the .NET version:

/usr/local/bin/uninstall_scalar.sh

After running the macOS installer, you will need to run scalar register . in your existing enlistments to ensure they are tracked by background maintenance and other changes in future versions. You can also run scalar register <path> for each <path> that was previously output by scalar list.

Instructions for Linux Users

The Linux installer will not uninstall the existing Scalar.NET installation, but it will replace the location of the scalar executable on the PATH. There is no established uninstall mechanism, but Scalar.NET can be removed via sudo rm -rf /usr/local/lib/scalar/.

After running the Linux installer (or compiling and installing from source), you will need to run scalar register . in your existing enlistments to ensure they are tracked by background maintenance and other changes in future versions.

Pull Requests since v2.32.0.vfs.0.1

• #373: Avoid using uninitialized variables in format_tracking_info()
• #375: gvfs-helper: always keep index-pack silent

The installer was updated with the intended default components, including the auto-upgrade prompt and the Scalar CLI.