Improve disk space recovery for partial clones

Personal Information:
—----------------------------------------------------------------------------------------------------------------------------
Name: Amisha Chhajed
Email: amishhhaaaa@gmail.com
github: https://github.com/amishhaa
Time Zone: UTC +5:30 (IST)
Education: SVKM's Dwarkadas J. Sanghvi College of Engineering
Year: 3rd year, 6th semester
Degree: Bachelor of Technology in Artificial Intelligence and Data Science

About me and past experience: —---------------------------------------------------------------------------------------------------------------------------- Hello, I am Amisha, currently in my penultimate year of engineering. I am deeply passionate about contributing to open source and find great fulfillment when I see my code helping people. Given this motivation, I have contributed to various open source projects and the experience has been extremely rewarding and ethereal. Apart from open source, I make art and I like building games.

I am currently doing my LFX at OpenTelemetry, my project is about building a GO CLI tool that runs tests of the dependents of a library to record any regresisons caused by new changes in the library (more about my project: https://mentorship.lfx.linuxfoundation.org/project/5f537fc2-548b-487a-99ed-c61f7e8bcd47) (list of PRs created until now: https://github.com/open-telemetry/opentelemetry-go-build-tools/issues?q=is%3Apr+author%3Aamishhaa). I interned at Google for summer of 2025 under team workspace serving infrastructure. (Completion certificate: https://drive.google.com/file/d/10Nze1RzAehyN_BogP4Qlc0fHFYYuJ5Rw/view?usp=sharing) Some open source contributions that I am most proud of are in bitcoin core (refer credits: https://bitcoincore.org/en/releases/29.2/ my PR: https://github.com/bitcoin/bitcoin/pull/33482) and git :)

My contributions in git:
* cat-file: exit code of 'git cat-file' is suppressed by piping it
directly into grep.
*Status: Awaiting review
*Mailing List: https://lore.kernel.org/git/20260113180409.36683-1-amishhhaaaa@gmail.com/
*Log: This was the first patch i ever created for git as amicroproject,
made me familiar with the mailing list workflow.

* sparse-checkout: optimize string_list construction and add tests to
verify deduplication.
*Status: merged in 'master'
*Mailing List: https://lore.kernel.org/git/20260121130005.72375-1-amishhhaaaa@gmail.com/
*Log: This is a really important patch for me, improves O(n^2)
complexity to O(n log n) of sparse-checkout by building a
sorted 'string_list' by constructing it unsorted then sorting it
followed by removing duplicates, this triggered a series of patches
and uncovered various bugs when i worked on replacing
calls of string_list_sort() and string_list_remove_duplicates()
with string_list_sort_u().

*u-string-list: add unit tests for string-list methods.
*Status: merged in 'master'
*Mailing List: https://lore.kernel.org/git/20260129121220.69267-1-amishhhaaaa@gmail.com/
Log: Adding unit tests for string-list methods which i saw were not
present when i was creating a new API string_list_sort_u.

* string-list: add string_list_sort_u() that mimics "sort -u"
*Status: merged in 'master'
*Mailing List: https://lore.kernel.org/git/20260129121220.69267-2-amishhhaaaa@gmail.com/
Log: Adding a new API string_list_sort_u and cleaning up the call
sites that can directly adopt this new replacement,
string_list_sort_u mimics sort -u.

*sparse-checkout: use string_list_sort_u *Status: merged in 'master' *Mailing List: https://lore.kernel.org/git/20260212041017.91370-2-amishhhaaaa@gmail.com/ *Log: Small fix to replace a callsite of string_list_sort and string_list_remove_duplicates with string_list_sort_u.

*help: cleanup the construction of keys_uniq *Status: Will merge to 'next'. *Mailing List: https://lore.kernel.org/git/20260311192453.62213-1-amishhhaaaa@gmail.com/ *Log: Cleaning up complex callsites of string_list_sort and string_list_remove_duplicates, this one involved finding a test case that demonstrated a breakage, https://lore.kernel.org/git/CAPvEtrenMBMFaMxcCR4VwoyMFU-_Z+bqq5nJaWv5eyn3HRutEA@mail.gmail.com/, then replacing them with string_list_sort_u, another bug found as an effort is https://lore.kernel.org/git/CAPvEtrfEZXHxcDf=z60ODfUA8cS81rhF1y7KEZApEBby7aCa1A@mail.gmail.com/, This is still a pending bug which is good to work around in future, I have provided a test to demonstrate an existing breakage.

History/Background and Overview: —---------------------------------------------------------------------------------------------------------------------------- Building partial clone was a community effort, with contributions referenced here, https://git-scm.com/docs/partial-clone#_related_links, even though partial clone is working, there is currently no direct way to evict the acquired blobs and reduce the disk space that we bloated by constant use.

The "Partial Clone" feature is a performance optimization for Git that allows Git to function without having a complete copy of the repository, however overtime a lot of blobs might be fetched and currently there is no functionality that, first checks if a blob is present on a promisor and then we can remove it safely to free up our disk space, fundamentally users who make a partial clone want to save up space so being able to remove the acquired blobs on demand would be a great addition.

This project aims to implement a command 'git evict' that can carry out safe removal of the blobs from our disk space such that it can be fetched later on from any of the remotes if needed, dynamically.

Proposed Plan: —---------------------------------------------------------------------------------------------------------------------------- Whenever we are evicting something we are unsure of its usefullness to users, unless obvious, which git gc already handles. To overcome this, we can make a new command 'git evict', essentially this command gives users options and freedom to evict blobs that they no longer require, whether it is out of cone or not on a checkout and a lot of other situations, instead of predicting what users may or may not need we can give them the choice of removal. In a case where users have a cone and have set up a maintenance task of evicting blobs outside of cone, in that case we can make it automatic.

This command would check for presence of promisor remotes for blobs that user has set to remove, if a promisor is promising that object we can evict it, otherwise we keep it. This would also require users to be online, as we cannot and should not evict something that is not promised.

As git currently treats remotes as source of truth(.promisor), we also trust those remotes when evicting blobs because if all the remotes break the principal of not strictly presenting the promised objects then the partial clone is inherently broken, we can display a warning that remote might not be able to fetch your file again if it gets deleted there while evicting based on .promisor file.

Currently on the user interface I am planning to implement these
flags, inspired heavily from reversing how we partial clone, for say
when partial cloning i set blob:limit=<size> then i might want to evict blobs
greater than that size in future.
* --outside-cone: Evict blobs that are not part of the current
sparse-checkout cone.
* --older-than=<time>: Evict blobs that haven't been referenced by a
commit in the last N days.
(Suggested :- https://lore.kernel.org/git/735eb76e-44a9-4f79-b769-23a3a07437ae@gmail.com/)
* --large-only=<size>: Evict blobs that are bigger than a certain size.
* --tree-depth=<n>: Evict blobs with depth > n

This project can essentially be split into two parts:
* Given an object, we can use method is_promisor_object() to check if
it is promised, if yes we can repack our packfiles without that object,
however we cannot repack for every object hence first we need to gather
a list of objects and after running is_promisor_object() for each of
them, we can repack without the objects we are evicting.
* Now comes gathering the list of objects, for each command written
above we would need a different method to find and append the object
to evict, in the object list. For example, for objects --large-only=<size>,
we need to find objects that are larger than the size specified and mark it for
eviction, similar methods to handle such filters have been written in our
codebase and can be used as reference.

Project Timeline:
—----------------------------------------------------------------------------------------------------------------------------
* Community Bonding (Until May 24)
Discuss project ideas and design implementation details with mentors,
possible subcommands to keep and the overall architecture of command,
any optimizations we can make when repacking objects.

* Coding Period (May 25 - August 16)
The implementation flow can be divided as,
* Implement evict_objects method and is_safe_to_evict method.
* Implement different ways to gather and pass the objects to the
evict_objects method.
* implement git evict command.
* All stages would be accompanied by necessary documentation and unit tests.

* Final Week (August 17 - August 24)
This is a buffer period for any unforeseen delays and to prepare a
final report of everything we have accomplished over the summer :)

Availability: —---------------------------------------------------------------------------------------------------------------------------- I would be dedicating 45 hours per week of my time to this project weekly. I don't have any other commitments apart from LFX in the month of May which would be easy to manage given my summer break.

Post-GSOC and Appreciation: —---------------------------------------------------------------------------------------------------------------------------- I want my journey with git to be a long one, it is very fulfilling for me to see my code running on many devices, It is like a dream come true for me, so even post GSOC I intend to keep contributing to git.