App::GitWorkspaceScanner - Scan git repositories in your workspace for local changes not synced up.


Version 1.1.0


This module scans a workspace to find git repositories that are not in sync with their remotes or that are not on an expected branch. This gives you a snapshot of all outstanding changes in your entire workspace.


        sudo nice ./scan_git_repositories


Git::WorkspaceScanner provides a scan_git_repositories utility as a command line interface to the module. It supports the following command line options:

  • --verbose

    Print out information about the analysis performed. Off by default.

            # Print out information.
            ./scan_git_repositories --verbose
  • --workspace

    Root of the workspace to search git repositories into. By default, the search is performed on '/', but you can use any absolute path.

            ./scan_git_repositories --workspace=$HOME
  • --allow_untracked_files

    Set whether untracked files should generate a warning in the report. Currently on by default, but this is likely to change in the near future as we add/clean up our .gitignore files.

            # Do not warn on untracked files (default).
            ./scan_git_repositories --allow_untracked_files=0
            # Warn on untracked files.
            ./scan_git_repositories --allow_untracked_files=1
  • --allowed_branches

    Generate a warning if the current branch doesn't match one of the branches specified. Set to master default.

            # Allow only using the master branch.
            # Allow only using the master branch.
            ./scan_git_repositories --allowed_branches=master
            # Allow only using the master and production branches.
            ./scan_git_repositories --allowed_branches=master,production
  • --allow_any_branches

    Disable the check performed by --allowed_branches, which is set to force using the master branch by default.

            # Don't check the branch the repository is on.
            ./scan_git_repositories --allow_any_branches=1
  • --whitelist_repositories

    Excludes specific repositories from the checks performed by this script. The argument accepts a comma-separated list of paths to ignore, but by default no repositories are whitelisted.

            # Whitelist /root/my_custom_repo
            ./scan_git_repositories --whitelist_repositories=/root/my_custom_repo


  • This script currently uses locate to scan the current machine for git repositories, so this only works for Linux/Unix machines.

  • If you are not using --workspace to limit the scan to files on which you have read permissions, this script needs to be run as root.

  • You should have updatedb in your crontab running daily, to ensure that new repositories are picked up.

  • You should run this script using nice. While it uses locate, it still has an impact on the file cache and using nice will help mitigate any potential issues.



Create a new Git::WorkspaceScanner object.

        my $scanner = Git::WorkspaceScanner->new(
                arguments => \@arguments,


  • arguments (mandatory)

    An arrayref of arguments passed originally to the command line utility.


Parse the options passed via the command line arguments and make sure there is no conflict or invalid settings.

        my $options = $scanner->parse_arguments();


Return a list of all the git repositories on the machine.

        my $git_repositories = get_git_repositories();


Return a list of repositories with local modifications not reflected on the origin repository.

        my $unclean_repositories = $app->get_unclean_repositories( $git_repositories );

The return value is a hashref, with the key being the path to the git repository and the value the git status for that git repository.



Please report any bugs or feature requests through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

        perldoc App::GitWorkspaceScanner

You can also look for information at:


Guillaume Aubert, <aubertg at>.


Copyright 2014-2017 Guillaume Aubert.

This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for more details.