Skip to content


Merge pull request #2974 from derrickstolee/maintenance-and-headless
Browse files Browse the repository at this point in the history
Include Windows-specific maintenance and headless-git
  • Loading branch information
dscho committed Jan 11, 2021
2 parents fde3e95 + bd103b3 commit f8cbc84
Show file tree
Hide file tree
Showing 8 changed files with 743 additions and 35 deletions.
116 changes: 116 additions & 0 deletions Documentation/git-maintenance.txt
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,122 @@ 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


The standard mechanism for scheduling background tasks on POSIX systems
is cron(8). 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:

# 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


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 `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. 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
the crontab(5) 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


While macOS technically supports `cron`, using `crontab -e` requires
elevated privileges and the executed process does not have a full user
context. Without a full user context, Git and its credential helpers
cannot access stored credentials, so some maintenance tasks are not

Instead, `git maintenance start` interacts with the `launchctl` tool,
which is the recommended way to schedule timed jobs in macOS. Scheduling
maintenance through `git maintenance (start|stop)` requires some
`launchctl` features available only in macOS 10.11 or later.

Your user-specific scheduled tasks are stored as XML-formatted `.plist`
files in `~/Library/LaunchAgents/`. You can see the currently-registered
tasks using the following command:

$ ls ~/Library/LaunchAgents/org.git-scm.git*

One task is registered for each `--schedule=<frequency>` option. To
inspect how the XML format describes each schedule, open one of these
`.plist` files in an editor and inspect the `<array>` element following
the `<key>StartCalendarInterval</key>` element.

`git maintenance start` will overwrite these files and register the
tasks again with `launchctl`, so any customizations should be done by
creating your own `.plist` files with distinct names. Similarly, the
`git maintenance stop` command will unregister the tasks with `launchctl`
and delete the `.plist` files.

To create more advanced customizations to your background tasks, see
launchctl.plist(5) for more information.


Windows does not support `cron` and instead has its own system for
scheduling background tasks. The `git maintenance start` command uses
the `schtasks` command to submit tasks to this system. You can inspect
all background tasks using the Task Scheduler application. The tasks
added by Git have names of the form `Git Maintenance (<frequency>)`.
The Task Scheduler GUI has ways to inspect these tasks, but you can also
export the tasks to XML files and view the details there.

Note that since Git is a console application, these background tasks
create a console window visible to the current user. This can be changed
manually by selecting the "Run whether user is logged in or not" option
in Task Scheduler. This change requires a password input, which is why
`git maintenance start` does not select it by default.

If you want to customize the background tasks, please rename the tasks
so future calls to `git maintenance (start|stop)` do not overwrite your
custom tasks.

Expand Down
7 changes: 7 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -2514,6 +2514,13 @@ compat/nedmalloc/nedmalloc.sp compat/nedmalloc/nedmalloc.o: EXTRA_CPPFLAGS = \
compat/nedmalloc/nedmalloc.sp: SP_EXTRA_FLAGS += -Wno-non-pointer-null

headless-git.o: compat/win32/headless.c
-fno-stack-protector -o $@ -c -Wall -Wwrite-strings $<

headless-git$X: headless-git.o git.res
$(QUIET_LINK)$(CC) $(ALL_LDFLAGS) -mwindows $(COMPAT_CFLAGS) -o $@ $^

$(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) $(LIBS)

Expand Down

0 comments on commit f8cbc84

Please sign in to comment.