I'm running git gc --auto as part of an automatic saves script. I'd like to run further cleanup if git gc --auto has done something, but I'd like to spare the hassle if git gc --auto doesn't feel like something need to be done. Is there a way to check the return value of git gc --auto, or to check beforehand if it is necessary to run it ?
How can I know if `git gc --auto` has done something?
17.1k Views Asked by Vincent Fourmond At
3
There are 3 best solutions below
0
On
Update Sept. 2020: you won't have to run only git gc --auto as part of your automatic saves script.
The old "gc" can now be superseded by the new git maintenance run --auto.
And it can display what it is doing.
With Git 2.29 (Q4 2020), A "git gc"(man)'s big brother has been introduced to take care of more repository maintenance tasks, not limited to the object database cleaning.
See commit 25914c4, commit 4ddc79b, commit 916d062, commit 65d655b, commit d7514f6, commit 090511b, commit 663b2b1, commit 3103e98, commit a95ce12, commit 3ddaad0, commit 2057d75 (17 Sep 2020) by Derrick Stolee (derrickstolee).
(Merged by Junio C Hamano -- gitster -- in commit 48794ac, 25 Sep 2020)
maintenance: create basic maintenance runnerHelped-by: Jonathan Nieder
Signed-off-by: Derrick Stolee
The 'gc' builtin is our current entrypoint for automatically maintaining a repository. This one tool does many operations, such as:
- repacking the repository,
- packing refs, and
- rewriting the commit-graph file.
The name implies it performs "garbage collection" which means several different things, and some users may not want to use this operation that rewrites the entire object database.
Create a new '
maintenance' builtin that will become a more general- purpose command.To start, it will only support the '
run' subcommand, but will later expand to add subcommands for scheduling maintenance in the background.For now, the '
maintenance' builtin is a thin shim over the 'gc' builtin.
In fact, the only option is the '--auto' toggle, which is handed directly to the 'gc' builtin.
The current change is isolated to this simple operation to prevent more interesting logic from being lost in all of the boilerplate of adding a new builtin.Use existing
builtin/gc.cfile because we want to share code between the two builtins.
It is possible that we will have 'maintenance' replace the 'gc' builtin entirely at some point, leaving 'git gc(man)' as an alias for some specific arguments to 'git maintenance run'.Create a new
test_subcommandhelper that allows us to test if a certain subcommand was run. It requires storing theGIT_TRACE2_EVENTlogs in a file.
A negation mode is available that will be used in later tests.
(That last part is one way to ascertain the new git maintainance run --auto does something)
git maintenance now includes in its man page:
git-maintenance(1)
NAME
git-maintenance- Run tasks to optimize Git repository dataSYNOPSIS
[verse] 'git maintenance' run [<options>]DESCRIPTION
Run tasks to optimize Git repository data, speeding up other Git commands and reducing storage requirements for the repository.
Git commands that add repository data, such as
git addorgit fetch, are optimized for a responsive user experience. These commands do not take time to optimize the Git data, since such optimizations scale with the full size of the repository while these user commands each perform a relatively small action.The
git maintenancecommand provides flexibility for how to optimize the Git repository.SUBCOMMANDS
runRun one or more maintenance tasks.
TASKS
gcClean up unnecessary files and optimize the local repository. "GC" stands for "garbage collection," but this task performs many smaller tasks. This task can be expensive for large repositories, as it repacks all Git objects into a single pack-file. It can also be disruptive in some situations, as it deletes stale data. See
git gcfor more details on garbage collection in Git.OPTIONS
--autoWhen combined with the
runsubcommand, run maintenance tasks only if certain thresholds are met. For example, thegctask runs when the number of loose objects exceeds the number stored in thegc.autoconfig setting, or when the number of pack-files exceeds thegc.autoPackLimitconfig setting.
maintenance: replacerun_auto_gc()Signed-off-by: Derrick Stolee
The
run_auto_gc()method is used in several places to trigger a check for repo maintenance after some Git commands, such as 'git commit'(man) or 'git fetch'(man).To allow for extra customization of this maintenance activity, replace the '
git gc --auto [--quiet](man)' call with one to 'git maintenance run --auto [--quiet](man)'.
As we extend the maintenance builtin with other steps, users will be able to select different maintenance activities.Rename
run_auto_gc()torun_auto_maintenance()to be clearer what is happening on this call, and to expose all callers in the current diff. Rewrite the method to use a structchild_processto simplify the calls slightly.Since '
git fetch'(man) already allows disabling the 'git gc --auto'(man) subprocess, add an equivalent option with a different name to be more descriptive of the new behavior: '--[no-]maintenance'.
fetch-options now includes in its man page:
Run
git maintenance run --autoat the end to perform automatic repository maintenance if needed. (--[no-]auto-gcis a synonym.)
This is enabled by default.
git clone now includes in its man page:
which automatically call
git maintenance run --auto. (Seegit maintenance.)
Plus, your save script will be able to make git maintenance do more than git gc ever could, thanks to tasks.
maintenance: add --task optionSigned-off-by: Derrick Stolee
A user may want to only run certain maintenance tasks in a certain order.
Add the
--task=<task>option, which allows a user to specify an ordered list of tasks to run. These cannot be run multiple times, however.Here is where our array of
maintenance_taskpointers becomes critical. We can sort the array of pointers based on the task order, but we do not want to move the struct data itself in order to preserve the hashmap references. We use the hashmap to match the --task= arguments into the task struct data.Keep in mind that the '
enabled' member of themaintenance_taskstruct is a placeholder for a future 'maintenance.<task>.enabled' config option. Thus, we use the 'enabled' member to specify which tasks are run when the user does not specify any--task=<task>arguments.
The 'enabled' member should be ignored if--task=<task>appears.
git maintenance now includes in its man page:
Run one or more maintenance tasks. If one or more
--task=<task>options are specified, then those tasks are run in the provided order. Otherwise, only thegctask is run.
git maintenance now includes in its man page:
--task=<task>If this option is specified one or more times, then only run the specified tasks in the specified order. See the 'TASKS' section for the list of accepted
<task>values.
And:
maintenance: create maintenance..enabled configSigned-off-by: Derrick Stolee
Currently, a normal run of "
git maintenance run"(man) will only run the 'gc' task, as it is the only one enabled.
This is mostly for backwards-compatible reasons since "git maintenance run --auto"(man) commands replaced previous "git gc --auto" commands after some Git processes.Users could manually run specific maintenance tasks by calling "
git maintenance run --task=<task>" directly.Allow users to customize which steps are run automatically using config. The '
maintenance.<task>.enabled' option then can turn on these other tasks (or turn off the 'gc' task).
git config now includes in its man page:
maintenance.<task>.enabledThis boolean config option controls whether the maintenance task with name
<task>is run when no--taskoption is specified togit maintenance run. These config values are ignored if a--taskoption exists.
By default, onlymaintenance.gc.enabledis true.
git maintenance now includes in its man page:
Run one or more maintenance tasks. If one or more
--taskoptions are specified, then those tasks are run in that order. Otherwise, the tasks are determined by whichmaintenance.<task>.enabledconfig options are true.
By default, onlymaintenance.gc.enabledis true.
git maintenance now also includes in its man page:
If no
--task=<task>arguments are specified, then only the tasks withmaintenance.<task>.enabledconfigured astrueare considered.
Another way to know if the new git maintenance run is doing currently anything is to check for a lock (.git/maintenance.lock file):
maintenance: take a lock on the objects directorySigned-off-by: Derrick Stolee
Performing maintenance on a Git repository involves writing data to the
.gitdirectory, which is not safe to do with multiple writers attempting the same operation.
Ensure that only one 'git maintenance'(man) process is running at a time by holding a file-based lock.Simply the presence of the
.git/maintenance.lockfile will prevent future maintenance. This lock is never committed, since it does not represent meaningful data. Instead, it is only a placeholder.If the lock file already exists, then no maintenance tasks are attempted. This will become very important later when we implement the '
prefetch' task, as this is our stop-gap from creating a recursive process loop between 'git fetch'(man) ' and 'git maintenance run --auto(man).
You can also check if git gc/git maintenance will have to do anything.
With Git 2.29 (Q4 2020), A "git gc"(man) 's big brother has been introduced to take care of more repository maintenance tasks, not limited to the object database cleaning.
See commit 25914c4, commit 4ddc79b, commit 916d062, commit 65d655b, commit d7514f6, commit 090511b, commit 663b2b1, commit 3103e98, commit a95ce12, commit 3ddaad0, commit 2057d75 (17 Sep 2020) by Derrick Stolee (derrickstolee).
(Merged by Junio C Hamano -- gitster -- in commit 48794ac, 25 Sep 2020)
maintenance: use pointers to check--autoSigned-off-by: Derrick Stolee
The '
git maintenance run(man) ' command has an '--auto' option. This is used by other Git commands such as 'git commit(man) ' or 'git fetch(man) ' to check if maintenance should be run after adding data to the repository.Previously, this
--autooption was only used to add the argument to the 'git gc'(man) command as part of the 'gc' task.
We will be expanding the other tasks to perform a check to see if they should do work as part of the--autoflag, when they are enabled by config.
First, update the 'gc' task to perform the auto check inside the maintenance process.
This prevents running an extra 'git gc --auto'(man) command when not needed.
It also shows a model for other tasks.Second, use the '
auto_condition' function pointer as a signal for whether we enable the maintenance task under '--auto'.
For instance, we do not want to enable the 'fetch' task in '--auto' mode, so that function pointer will remainNULL.We continue to pass the '--auto' option to the '
git gc'(man) command when necessary, because of thegc.autoDetachconfig option changes behavior.
Likely, we will want to absorb the daemonizing behavior implied bygc.autoDetachas amaintenance.autoDetachconfig option.
To illustrate what git maintenance will do that git gc won't:
maintenance: add commit-graph taskSigned-off-by: Derrick Stolee
The first new task in the '
git maintenance(man) ' builtin is the 'commit-graph' task.
This updates the commit-graph file incrementally with the commandgit commit-graph write --reachable --splitBy writing an incremental commit-graph file using the "
--split" option we minimize the disruption from this operation.The default behavior is to merge layers until the new "top" layer is less than half the size of the layer below. This provides quick writes most of the time, with the longer writes following a power law distribution.
Most importantly, concurrent Git processes only look at the commit-graph-chain file for a very short amount of time, so they will very likely not be holding a handle to the file when we try to replace it. (This only matters on Windows.)
If a concurrent process reads the old commit-graph-chain file, but our job expires some of the
.graphfiles before they can be read, then those processes will see a warning message (but not fail). This could be avoided by a future update to use the--expire-timeargument when writing the commit-graph.
git maintenance now includes in its man page:
commit-graphThe
commit-graphjob updates thecommit-graphfiles incrementally, then verifies that the written data is correct.The incremental write is safe to run alongside concurrent Git processes since it will not expire
.graphfiles that were in the previouscommit-graph-chainfile. They will be deleted by a later run based on the expiration delay.
And:
maintenance: add auto condition forcommit-graphtaskSigned-off-by: Derrick Stolee
Instead of writing a new
commit-graphin every 'git maintenance run --auto'(man) process (whenmaintenance.commit-graph.enabledis configured to betrue), only write when there are "enough" commits not in acommit-graphfile.This count is controlled by the
maintenance.commit-graph.autoconfig option.To compute the count, use a depth-first search starting at each ref, and leaving markers using the
SEENflag.
If this count reaches the limit, then terminate early and start the task.
Otherwise, this operation will peel every ref and parse the commit it points to. If these are all in thecommit-graph, then this is typically a very fast operation.Users with many refs might feel a slow-down, and hence could consider updating their limit to be very small. A negative value will force the step to run every time.
git config now includes in its man page:
maintenance.commit-graph.autoThis integer config option controls how often the
commit-graphtask should be run as part ofgit maintenance run --auto.
- If zero, then the
commit-graphtask will not run with the--autooption.- A negative value will force the task to run every time.
- Otherwise, a positive value implies the command should run when the number of reachable commits that are not in the commit-graph file is at least the value of
maintenance.commit-graph.auto.The default value is 100.
With Git 2.30 (Q1 2021), the test-coverage enhancement of running commit-graph task "git maintenance"(man) as needed led to discovery and fix of a bug.
See commit d334107 (12 Oct 2020), and commit 8f80180 (08 Oct 2020) by Derrick Stolee (derrickstolee).
(Merged by Junio C Hamano -- gitster -- in commit 0be2d65, 02 Nov 2020)
maintenance: test commit-graph auto conditionSigned-off-by: Derrick Stolee
The auto condition for the
commit-graphmaintenance task walks refs looking for commits that are not in thecommit-graphfile.
This was added in 4ddc79b2 ("maintenance: add auto condition for commit-graph task", 2020-09-17, Git v2.29.0-rc0 -- merge listed in batch #17) but was left untested.The initial goal of this change was to demonstrate the feature works properly by adding tests. However, there was an off-by-one error that caused the basic tests around
maintenance.commit-graph.auto=1to fail when it should work.The subtlety is that if a ref tip is not in the
commit-graph, then we were not adding that to the total count. In the test, we see that we have only added one commit since our last commit-graph write, so the auto condition would say there is nothing to do.The fix is simple: add the check for the
commit-graphposition to see that the tip is not in thecommit-graphfile before starting our walk. Since this happens before adding to the DFS stack, we do not need to clear our (currently empty) commit list.This does add some extra complexity for the test, because we also want to verify that the walk along the parents actually does some work. This means we need to add at least two commits in a row without writing the
commit-graph. However, we also need to make sure no additional refs are pointing to the middle of this list or else thefor_each_ref()inshould_write_commit_graph()might visit these commits as tips instead of doing a DFS walk. Hence, the last two commits are added with "git commit"(man) instead of"test_commit".
With Git 2.30 (Q1 2021), "git maintenance(man) run/start/stop" needed to be run in a repository to hold the lockfile they use, but didn't make sure they are actually in a repository, which has been corrected.
See commit 0a1f2d0 (08 Dec 2020) by Josh Steadmon (steadmon).
See commit e72f7de (26 Nov 2020) by Rafael Silva (raffs).
(Merged by Junio C Hamano -- gitster -- in commit f2a75cb, 08 Dec 2020)
maintenance: fix SEGFAULT when no repositorySigned-off-by: Rafael Silva
Reviewed-by: Derrick Stolee
The "
git maintenance run git"(man) and "git maintenance start/stop" commands holds a file-based lock at the.git/maintenance.lockand.git/schedule.lockrespectively. These locks are used to ensure only one maintenance process is executed at the time as both operations involves writing data into the repository.The path to the lock file is built using
"the_repository->objects->odb->path"that results in SEGFAULT when we have no repository available as `"`the_repository->objects->odb"is set toNULL.Let's teach maintenance command to use
RUN_SETUPoption that will provide the validation and fail when running outside of a repository. Hence fixing the SEGFAULT for all three operations and making the behaviour consistent across all subcommands.Setting the
RUN_SETUPalso provides the same protection for all subcommands given that the "register" and "unregister" also requires to be executed inside a repository.Furthermore let's remove the local validation implemented by the "register" and "unregister" as this will not be required anymore with the new option.
0
On
If you are monitoring git gc --auto exit status (for detecting a failure for instance), that return value has changed with Git 2.20:
See commit 3029970 (17 Jul 2018) by Jonathan Nieder (artagnon).
Helped-by: Jeff King (peff).
(Merged by Junio C Hamano -- gitster -- in commit 993fa56, 16 Oct 2018)
gc: exit with status 128 on failureA value of
-1returned fromcmd_gc getspropagated toexit(), resulting in an exit status of 255.
Use die instead for a clearer error message and a controlled exit.
Instead of "error: The last gc run reported the following.", you now have:
fatal: The last gc run reported the following
With Git 2.30 (Q1 2021), "
git maintenance"(man) , the extended big brother of "git gc"(man) presented in the previous answer, continues to evolve.It is more precise than
git gcand the options introduced in 2.30 allow to know when it has done something, as asked in the OP.See commit e841a79, commit a13e3d0, commit 52fe41f, commit efdd2f0, commit 18e449f, commit 3e220e6, commit 252cfb7, commit 28cb5e6 (25 Sep 2020) by Derrick Stolee (
derrickstolee).(Merged by Junio C Hamano --
gitster-- in commit 52b8c8c, 27 Oct 2020)git maintenancenow includes in its man page:And:
git confignow includes in its man page:With Git 2.30 (Q1 2021), adds parts of "
git maintenance"(man) to ease writing crontab entries (and other scheduling system configuration) for it.See commit 0016b61, commit 61f7a38, commit a4cb1a2 (15 Oct 2020), commit 2fec604, commit 0c18b70, commit 4950b2a, commit b08ff1f (11 Sep 2020), and commit 1942d48 (28 Aug 2020) by Derrick Stolee (
derrickstolee).(Merged by Junio C Hamano --
gitster-- in commit 7660da1, 18 Nov 2020)git maintenancenow includes in its man page: