| Message ID | 99170df4626544c1dc26d2e188b215a776140a32.1605647598.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Maintenance IV: Platform-specific background maintenance | expand |
On Tue, Nov 17, 2020 at 4:13 PM Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com> wrote: > Advanced and expert users may want to know how 'git maintenance start' > schedules background maintenance in order to customize their own > schedules beyond what the maintenance.* config values allow. Start a new > set of sections in git-maintenance.txt that describe how 'cron' is used > to run these tasks. > > This is particularly valuable for users who want to inspect what Git is > doing or for users who want to customize the schedule further. Having a > baseline can provide a way forward for users who have never worked with > cron schedules. > > Signed-off-by: Derrick Stolee <dstolee@microsoft.com> > --- > diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt > @@ -218,6 +218,60 @@ Further, the `git gc` command should not be combined with > +The comments are used as a region to mark the schedule as written by Git. > +Any modifications within this region will be completely deleted by > +`git maintenance stop` or overwritten by `git maintenance start`. > + > +The `<path>` string is loaded to specifically use the location for the > +`git` executable used in the `git maintenance start` command. This allows > +for multiple versions to be compatible. However, if the same user runs > +`git maintenance start` with multiple Git executables, then only the > +latest executable will be used. It looks like this section in v4 got accidentally reverted to the wording from v2, whereas v3 had been changed to: The `crontab` entry specifies the full path of the `git` executable to ensure that the executed `git` command is the same one with which `git maintenance start` was issued independent of `PATH`. If the same user runs `git maintenance start` with multiple Git executables, then only the latest executable is used. > +These commands use `git for-each-repo --config=maintenance.repo` to run > +`git maintenance run --schedule=<frequency>` on each repository listed in > +the multi-valued `maintenance.repo` config option. These are typically > +loaded from the user-specific global config located at `~/.gitconfig`. > +The `git maintenance` process then determines which maintenance tasks > +are configured to run on each repository with each `<frequency>` using > +the `maintenance.<task>.schedule` config options. These values are loaded > +from the global or repository config values. Same problem here. This wording is from v2, whereas v3 had been changed to say generically "user-specific global config" rather than mentioning `~/.gitconfig` explicitly. > +If the config values are insufficient to achieve your desired background > +maintenance schedule, then you can create your own schedule. If you run > +`crontab -e`, then an editor will load with your user-specific `cron` > +schedule. In that editor, you can add your own schedule lines. You could > +start by adapting the default schedule listed earlier, or you could read > +https://man7.org/linux/man-pages/man5/crontab.5.html[the `crontab` documentation] > +for advanced scheduling techniques. Please do use the full path and > +`--exec-path` techniques from the default schedule to ensure you are > +executing the correct binaries in your schedule. And here too. v3 had updated this to say only "crontab(5)" rather than providing an explicit URL.
On 11/17/2020 7:34 PM, Eric Sunshine wrote: > On Tue, Nov 17, 2020 at 4:13 PM Derrick Stolee via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> Advanced and expert users may want to know how 'git maintenance start' >> schedules background maintenance in order to customize their own >> schedules beyond what the maintenance.* config values allow. Start a new >> set of sections in git-maintenance.txt that describe how 'cron' is used >> to run these tasks. >> >> This is particularly valuable for users who want to inspect what Git is >> doing or for users who want to customize the schedule further. Having a >> baseline can provide a way forward for users who have never worked with >> cron schedules. >> >> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> >> --- >> diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt >> @@ -218,6 +218,60 @@ Further, the `git gc` command should not be combined with >> +The comments are used as a region to mark the schedule as written by Git. >> +Any modifications within this region will be completely deleted by >> +`git maintenance stop` or overwritten by `git maintenance start`. >> + >> +The `<path>` string is loaded to specifically use the location for the >> +`git` executable used in the `git maintenance start` command. This allows >> +for multiple versions to be compatible. However, if the same user runs >> +`git maintenance start` with multiple Git executables, then only the >> +latest executable will be used. > > It looks like this section in v4 got accidentally reverted to the > wording from v2, whereas v3 had been changed to:> > The `crontab` entry specifies the full path of the `git` > executable to ensure that the executed `git` command is the same > one with which `git maintenance start` was issued independent of > `PATH`. If the same user runs `git maintenance start` with > multiple Git executables, then only the latest executable is used. Embarassing. Thanks for the catch. Thanks, -Stolee
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index 6fec1eb8dc..4c7aac877d 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -218,6 +218,60 @@ Further, the `git gc` command should not be combined with but does not take the lock in the same way as `git maintenance run`. If possible, use `git maintenance run --task=gc` instead of `git gc`. +The following sections describe the mechanisms put in place to run +background maintenance by `git maintenance start` and how to customize +them. + +BACKGROUND MAINTENANCE ON POSIX SYSTEMS +--------------------------------------- + +The standard mechanism for scheduling background tasks on POSIX systems +is `cron`. This tool executes commands based on a given schedule. The +current list of user-scheduled tasks can be found by running `crontab -l`. +The schedule written by `git maintenance start` is similar to this: + +----------------------------------------------------------------------- +# BEGIN GIT MAINTENANCE SCHEDULE +# The following schedule was created by Git +# Any edits made in this region might be +# replaced in the future by a Git command. + +0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly +0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily +0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly + +# END GIT MAINTENANCE SCHEDULE +----------------------------------------------------------------------- + +The comments are used as a region to mark the schedule as written by Git. +Any modifications within this region will be completely deleted by +`git maintenance stop` or overwritten by `git maintenance start`. + +The `<path>` string is loaded to specifically use the location for the +`git` executable used in the `git maintenance start` command. This allows +for multiple versions to be compatible. However, if the same user runs +`git maintenance start` with multiple Git executables, then only the +latest executable will be used. + +These commands use `git for-each-repo --config=maintenance.repo` to run +`git maintenance run --schedule=<frequency>` on each repository listed in +the multi-valued `maintenance.repo` config option. These are typically +loaded from the user-specific global config located at `~/.gitconfig`. +The `git maintenance` process then determines which maintenance tasks +are configured to run on each repository with each `<frequency>` using +the `maintenance.<task>.schedule` config options. These values are loaded +from the global or repository config values. + +If the config values are insufficient to achieve your desired background +maintenance schedule, then you can create your own schedule. If you run +`crontab -e`, then an editor will load with your user-specific `cron` +schedule. In that editor, you can add your own schedule lines. You could +start by adapting the default schedule listed earlier, or you could read +https://man7.org/linux/man-pages/man5/crontab.5.html[the `crontab` documentation] +for advanced scheduling techniques. Please do use the full path and +`--exec-path` techniques from the default schedule to ensure you are +executing the correct binaries in your schedule. + GIT ---