https://github.com/gitwatch/gitwatch

Watch a file or folder and automatically commit changes to a git repo easily.
https://github.com/gitwatch/gitwatch

autocommit git

Last synced: about 2 months ago
JSON representation

Watch a file or folder and automatically commit changes to a git repo easily.

Host: GitHub
URL: https://github.com/gitwatch/gitwatch
Owner: gitwatch
License: gpl-3.0
Created: 2012-10-20T11:31:38.000Z (over 13 years ago)
Default Branch: master
Last Pushed: 2025-12-07T16:07:18.000Z (3 months ago)
Last Synced: 2025-12-10T02:58:30.128Z (3 months ago)
Topics: autocommit, git
Language: Shell
Homepage:
Size: 179 KB
Stars: 1,649
Watchers: 42
Forks: 222
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - gitwatch/gitwatch - Watch a file or folder and automatically commit changes to a git repo easily. (git)
awesome-starred-test - gitwatch/gitwatch - Watch a file or folder and automatically commit changes to a git repo easily. (Shell)
jimsghstars - gitwatch/gitwatch - Watch a file or folder and automatically commit changes to a git repo easily. (Shell)

README

- [gitwatch](#gitwatch)
- [What to use it for?](#what-to-use-it-for)
- [Installation](#installation)
- [From Source](#from-source)
- [Update](#update)
- [bpkg](#bpkg)
- [Archlinux](#archlinux)
- [NixOS](#nixos)
- [As Module](#as-module)
- [As Package](#as-package)
- [Docker](#docker)
- [Docker Compose (Recommended)](#docker-compose-recommended)
- [Using the Dockerfile](#using-the-dockerfile)
- [Requirements](#requirements)
- [Notes for Mac](#notes-for-mac)
- [What it does](#what-it-does)
- [Usage](#usage)
- [Starting on Boot](#starting-on-boot)
- [SysVInit](#sysvinit)
- [systemd](#systemd)
- [Other Articles](#other-articles)
- [On the Gitwatch Wiki](#on-the-gitwatch-wiki)
- [Community Articles](#community-articles)

# gitwatch

A bash script to watch a file or folder and commit changes to a git repo

## What to use it for?

That's really up to you, but here are some examples:

- **config files**: some programs auto-write their config files, without
waiting for you to click an 'Apply' button; or even if there is such a
button, most programs offer you no way of going back to an earlier
version of your settings. If you commit your config file(s) to a git
repo, you can track changes and go back to older versions. This script
makes it convenient, to have all changes recorded automatically.
- **document files**: if you use an editor that does not have built-in git
support (or maybe if you don't like the git support it has), you can use
gitwatch to automatically commit your files when you save them, or
combine it with the editor's auto-save feature to fully automatically and
regularly track your changes
- _more stuff!_ If you have any other uses, or can think of ones, please
let us know, and we can add them to this list!

## Installation

`gitwatch` can be installed in various ways.

### From Source

`gitwatch` can be installed from source by simply cloning the repository
and putting the shell script into your `$PATH`. The commands below will do
that for you if `/usr/local/bin` is in your `$PATH`. You may need to invoke
`install` with `sudo`.

```sh
git clone https://github.com/gitwatch/gitwatch.git
cd gitwatch
[sudo] install -b gitwatch.sh /usr/local/bin/gitwatch
```

#### Update

If you installed `gitwatch` from source, you can update it by following the
exact same steps (or `git pull` rather than clone if you kept the
repository around).

### bpkg

`gitwatch` can be installed with [bpkg](https://github.com/bpkg/bpkg). Make
sure you have [bpkg](https://github.com/bpkg/bpkg) installed before running
the command below. You may need to invoke `bpkg` with `sudo` when using the
`-g` flag.

```sh
[sudo] bpkg install -g gitwatch/gitwatch
```

### Archlinux

There is an [AUR](https://aur.archlinux.org/packages/gitwatch-git/) package
for Archlinux. Install it with you favorite aur helper.

### NixOS

Starting from NixOS 24.11 this package available in mainline. Additionally,
you can use receipts from this repository.

#### As Module

Each watching path should be described in _submodule_ `services.gitwatch.*`
like next:

```nix
services.gitwatch. = {
enable = true;
path = "/home/me/my-repo";
remote = "git@github.com:me/my-repo.git";
user = "me";
message = "Auto-commit by gitwatch on %d";
};
```

This will make NixOS to create `systemd` service named
`gitwatch-`. More details you can see at
`man configuration.nix`.

#### As Package

The `gitwatch` script available as package in _nixpkgs_;

## Docker

You can also run `gitwatch` inside a Docker container. This is useful for
isolating dependencies and ensuring a consistent environment.

### Docker Compose (Recommended)

The easiest way to run `gitwatch` with Docker is by using the provided
`docker-compose.yml` file.

**1. Prerequisites:**

- **Docker and Docker Compose**: Make sure you have both installed.
- [Install Docker](https://docs.docker.com/get-docker/)
- [Install Docker Compose](https://docs.docker.com/compose/install/)
- **A Git Repository**: You need a local directory that is a Git repository
you want to watch.
- **SSH Key**: For pushing to a remote repository, the container needs
access to an SSH key that is authorized with your Git provider.

**2. Docker Image Tags:**

This project publishes multiple Docker tags so you can choose the one that
best fits your use case.

The following image tags are available:

- `:`, `:`\
Always published for every build (immutable).

- `:master`\
Moving tag for the latest image from `master` branch.

- `:vX.Y`, `:X.Y`\
Published when a release tag `vX.Y` is pushed.

- `:latest`\
Updated when a `vX.Y` tag is pushed, pointing to the newest release
image.

**3. Configuration:**

The `docker-compose.yml` file is configured using environment variables.
You can either edit the `environment` section directly in the file or
create a `.env` file in the same directory to set the values.

Here's a breakdown of the important parts of the `docker-compose.yml` file:

- **`volumes`**: This is the most critical section to configure.
- `./watched-repo:/app/watched-repo`: This maps a directory from your
computer (the "host") into the container.
- You **must** change `./watched-repo` to the path of the local Git
repository you want `gitwatch` to monitor.
- `~/.ssh/id_rsa:/root/.ssh/id_rsa:ro`: This securely mounts your SSH
private key into the container in read-only mode (`ro`). This is
necessary for `gitwatch` to push changes to your remote repository.
- `~/.gitconfig:/root/.gitconfig:ro`: This mounts your Git configuration
into the container. This ensures that the commits made by `gitwatch`
are attributed to you with the correct name and email.
- **`environment`**: This section controls how `gitwatch` behaves.

**4. Environment Variables**

The following environment variables are available for configuring the
`gitwatch` container:

**5. Running gitwatch:**

- **Start the container** in the background (detached mode):

```sh
docker-compose up -d
```

- **View the logs** to see what `gitwatch` is doing:

```sh
docker-compose logs -f
```

- **Stop the container**:

```sh
docker-compose down
```

### Using the Dockerfile

If you prefer to build the Docker image yourself, you can use the provided
`Dockerfile`. This is useful if you want to customize the image with
additional tools or dependencies.

**1. Build the image:**

From the root of the `gitwatch` repository, run:

```sh
docker build -t gitwatch .
```

**2. Run the container:**

To run the container, you need to provide the same volumes and environment
variables as the Docker Compose setup.

```sh
docker run -d \
--name gitwatch \
-v /path/to/your/repo:/app/watched-repo \
-v ~/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
-v ~/.gitconfig:/root/.gitconfig:ro \
-e GIT_WATCH_DIR="/app/watched-repo" \
-e GIT_REMOTE="origin" \
-e GIT_BRANCH="main" \
gitwatch
```

**Important:** Remember to replace `/path/to/your/repo` with the actual
path to the Git repository you want to watch.

## Requirements

To run this script, you must have installed and globally available:

- `git` ([git/git](https://github.com/git/git) |
[git-scm](http://www.git-scm.com))
- `inotifywait` (part of
**[inotify-tools](https://github.com/rvoicilas/inotify-tools)**)

### Notes for Mac

If running on OS X, you'll need to install the following Homebrew tools:

```sh
brew install fswatch
brew install coreutils
```

## What it does

When you start the script, it prepares some variables and checks if the
file or directory given as input really exists.

Then it goes into the main loop (which will run forever, until the script
is forcefully stopped/killed), which will:

- watch for changes to the file/directory using `inotifywait`
(`inotifywait` will block until something happens)
- wait 2 seconds
- case file:
- `cd` into the directory containing the file (because `git` likes to
operate locally)
- `git add `
- `git commit -m "Scripted auto-commit on change ()"`
- case directory:
- `cd` into the directory (because `git` likes to operate locally)
- `git add --all .`
- `git commit -m "Scripted auto-commit on change ()"`
- if a remote is defined (with `-r`) do a push after the commit (a specific
branch can be selected with `-b`)

Notes:

- the waiting period of 2 sec is added to allow for several changes to be
written out completely before committing; depending on how fast the
script is executed, this might otherwise cause race conditions when
watching a folder
- currently, folders are always watched recursively

## Usage

`gitwatch.sh [-r [-b ]] `

It is expected that the watched file/directory are already in a git
repository (the script will not create a repository). If a folder is being
watched, this will be watched fully recursively; this also means that all
files and sub-folders added and removed from the directory will always be
added and removed in the next commit. The `.git` folder will be excluded
from the `inotifywait` call so changes to it will not cause unnecessary
triggering of the script.

If you have any large files in your repository that are changing
frequently, you might wish to ignore them with a `.gitignore` file.

### Starting on Boot

If you want to have the script auto-started upon boot, the method to do
this depends on your operating system and distribution. If you have a GUI
dialog to set up startup launches, you might want to use that, so you can
more easily find and change the startup script calls later on.

Please also note that if either of the paths involved (script or target)
contains spaces or special characters, you need to escape them accordingly;
if you don't know how to do that, the internet will help you, or feel free
to ask here or contact me directly.

#### SysVInit

A central place to put startup scripts on Linux is generally
`/etc/rc.local` (to my knowledge; only tested and confirmed on Ubuntu).
This file, if it has the +x bit, will be executed upon startup, **by the
root user account**. If you want to start `gitwatch` from `rc.local`, the
recommended way to call it is:

`su -c "/absolute/path/to/script/gitwatch.sh /absolute/path/to/watched/file/or/folder" -l &`

The `` bit should be replaced with your username or that of any
other (non-root) user account; it only needs write-access to the git
repository of the file/folder you want to watch. The ampersand (`&`) at the
end sends the launched process into the background (this is important if
you have other calls in `rc.local` after the mentioned line, because the
`gitwatch` call does not usually return).

#### systemd

- If installed to a path other than `/usr/local/bin/gitwatch`, modify
`gitwatch@.service` to suit
- Create dir if it does not exist and copy systemd service file with
`mkdir -p "$HOME/.config/systemd/user" && cp gitwatch@.service $HOME/.config/systemd/user`
- Start and enable the service for a given path by running
`systemctl --user --now enable gitwatch@$(systemd-escape "'-r url/to/repository' /path/to/folder").service`

## Other Articles

### On the Gitwatch Wiki

- [How to Install `Gitwatch` as a Debian Service With `supervisord`](https://github.com/gitwatch/gitwatch/wiki/gitwatch-as-a-service-on-Debian-with-supervisord)

### Community Articles

- [How To Use `Gitwatch` by Maisa Milena](https://medium.com/@maisa.milena/how-to-use-gitwatch-92c72e8ea4c4)
- [Syncing and Backing Up Your Thoughts with `Obsidian`, `Syncthing`, and `Gitwatch` by Vinícius Costa](https://viniciusnevescosta.medium.com/syncing-and-backing-up-your-thoughts-with-obsidian-syncthing-and-gitwatch-a55670b2b63f)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/gitwatch/gitwatch

Awesome Lists containing this project

README