About

A Simple Gem to keep multiple locally-cloned Git Repositories up to date.

The script will simply run git pull on every local clone of a git repository that it finds under the specified directory or directories.

Note: Versions prior to 0.9.4 had a serious bug where the script would crash on startup unless there was an exception: defined in the configuration file. This has been fixed from version 0.9.4 onwards.

Gem Version

Installation

A working copy of both Ruby and Git need to be installed on your machine. Git version 1.8.5 or greater is required, the script will not run with an older version or indeed without Git installed. Ruby version 1.9.3 and newer are supported.

Currently the script has only been tested under Linux, not Windows however Windows testing is next in the grand plan!

Simply install from the command prompt as you would any other gem. Note that you may require 'sudo' depending how Ruby is installed on your system.

gem install update_repo

Usage

Quick Start

Create a YAML-formatted configuration file called .updaterepo (note the 'dot' at the start!) in your home directory that contains at least a location: tag pointing to the directory containing the git repositories you wish to have updated :

                
                  ---
                  location:
                  - /media/myuser/git-repos
                  - /data/RepoDir

The directory or directories specified (there can be 1 root directory or as many as you wish) must already exist, and can be nested as deep as you wish with many repositories in many subdirectories.

This is the most basic example of a configuration file and there are other options that can be added to fine-tune the operation - see the description of configuration options below.

Now, run the script from anywhere :

update_repo

Note: From version 0.9.0 onwards, the default mode of operation is non-verbose. If you wish the same output as previous versions then specify --verbose on the command line or verbose: true in the configuration file.

Configuration

Configuration file

The configuration file defaults to ~/.updaterepo and is a standard YAML formatted text file. If this configuration file is not found, the script will terminate with an error.

The first line must contain only the YAML frontmatter of 3 dashes (---). After that, the following sections can follow in any order. Only the location: section is compulsory, and that must contain at least one entry.

location: - at least one directory which contains the locally cloned repository(s) to update. There is no limit on how many directories can be listed :

              
                ---
                location:
                - /media/myuser/git-repos
                - /data/RepoDir

exceptions: - an (optional) list of repositories that will NOT be updated automatically. Use this for repositories that need special handling, or should only be manually updated. Note that the name specified is that of the directory holding the repository (has the .git directory inside) :

              
                exceptions:
                - ubuntu-trusty
                - update_repo

log: - Log all output to the file updaterepo.log in the user's Home directory, defaults to FALSE (optional). This file would be overwritten on next run unless you also specify the timestamp: option. Equivalent to --log and --no-log on the command line.

              
                log: true

log_local: - Store the logfile (if this is enabled) in the current working directory instead of the Users' Home directory. Defaults to FALSE (optional). Equivalent to --log-local on the command line.

              
                log: true

timestamp: - timestamp the output files instead of overwriting them, defaults to FALSE (optional). Equivalent to --timestamp and --no-timestamp on the command line.

              
                timestamp: true

color: - Enable or disable coloured output, defaults to TRUE (optional). Equivalent to --color and --no-color on the command line.

              
                color: false

verbose: - Enable or disable Verbose mode, defaults to FALSE (optional). In this mode all the output of the git processes will be displayed to screen as will the local location and remote URL. Equivalent to --verbose and --no-verbose on the command line.

              
                verbose: true

verbose_errors: - Enable or disable Verbose error reporting in the summary, defaults to FALSE (optional). If this is set to TRUE, the end-of-job summary will list all the error output lines from any failing Git processes, not just the first line. Equivalent to --verbose-errors and --no-verbose-errors on the command line.

              
                verbose_errors: true

quiet: - Enable or disable Quiet mode, defaults to FALSE (optional). If this is specified then there will be nothing printed to the terminal except for fatal errors. Overrules the --verbose mode if also specified. Equivalent to --quiet and --no-quiet on the command line.

              
                quiet: true

Putting these together, below is an example .updaterepo file :

              
                ---
                location:
                - /media/myuser/git-repos
                - /data/RepoDir
                exceptions:
                - ubuntu-trusty
                - update_repo
                log: true
                timestamp: true
                color: false
                verbose: true
                verbose_errors: true
                quiet: false

Command line switches

Command line switches are not compulsory. If none are specified then the program will read from the standard configuration file ~/.updaterepo and automatically update the specified Repositories. However, if specified then they will take precedence over options from the configuration file.

Enter update_repo --help at the command prompt to get a list of available options :

              
                Options:
                  -c, --color, --no-color    Use colored output (default: true)
                  -d, --dump                 Dump a list of Directories and Git URL's to STDOUT in CSV format
                  -p, --prune=<i>            Number of directory levels to remove from the --dump output. Only valid when --dump or -d specified (Default: 0)
                  -l, --log                  Create a logfile of all program output to './update_repo.log'. Any older logs will be overwritten.
                  -t, --timestamp            Timestamp the logfile instead of overwriting. Does nothing unless the --log option is also specified.
                  -g, --log-local            Create the logfile in the current directory instead of in the users home directory
                  -r, --dump-remote          Create a dump to screen or log listing all the git remote URLS found in the specified directories.
                  -V, --verbose              Display each repository and the git output to screen
                  -E, --verbose-errors       List all the error output from a failing command in the summary, not just the first line
                  -q, --quiet                Run completely silent, with no output to the terminal (except fatal errors).
                  -v, --version              Print version and exit
                  -h, --help                 Show this message

Color

Determines if the output will be displayed in color or not. Default is TRUE. Note that regardless of this setting, when one of the '--dump-*' options is specified output will not be in color. No color codes will be saved to the logfile either.

Equivalent to the color: YAML configuration file tag.

  • Long-Form : --color
  • Short-Form : -c
  • Negative-Form : --no-color
  • Default : true

Dump

Dumps a CSV file of each directory and its associated git remote URL to the console, and to the logfile if that is enabled.

No equivalent in the YAML Configuration file.

  • Long-Form : --dump
  • Short-Form : -d
  • Negative-Form : None.
  • Default : false

Prune

Used in conjunction with the --dump option to remove the first <integer> directory levels from the output. This will enable it to be imported back into a different directory structure.

Equivalent to the prune: YAML configuration file tag.

  • Long-Form : --prune
  • Short-Form : -p
  • Negative-Form : None.
  • Default : 0

Log

Copies all script output to a logfile as well as STDOUT. The default logfile name is 'updaterepo.log' in the current users home directory. The previous log will be overwritten, but see the next option.

Equivalent to the log: YAML configuration file tag.

  • Long-Form : --log
  • Short-Form : -l
  • Negative-Form : --no-log
  • Default : false

Timestamp

Used in conjunction with the --log option to rename the logfile with an added timestamp, thus not overwriting older logs

Equivalent to the timestamp: YAML configuration file tag.

  • Long-Form : --timestamp
  • Short-Form : -t
  • Negative-Form : --no-timestamp
  • Default : false

Log Local

Store the logfile (if this is enabled) in the current working directory instead of the Users' Home directory

Equivalent to the log_local: YAML configuration file tag.

  • Long-Form : --log-local
  • Short-Form : -g
  • Negative-Form : --no-log-local
  • Default : false

Verbose

Display all raw Git output plus repository URL and location instead of the reduced output in the default mode. Note that the short-form command is the UPERCASE 'V' not lower!

Equivalent to the verbose: YAML configuration file tag.

  • Long-Form : --verbose
  • Short-Form : -V
  • Negative-Form : --no-verbose
  • Default : false

Verbose Errors

List all the error output from a failing command in the summary, not just the first line

Equivalent to the verbose_errors: YAML configuration file tag.

  • Long-Form : --verbose-errors
  • Short-Form : -E
  • Negative-Form : --no-verbose-errors
  • Default : false

Quiet

No output will be displayed to screen during the running of script, except for any fatal errors.

Equivalent to the quiet: YAML configuration file tag.

  • Long-Form : --quiet
  • Short-Form : -q
  • Negative-Form : --no-quiet
  • Default : false

Dump Remotes

Dumps a bare list to the console of all the Git remote URL's found in the specified directories. This can be saved by redirecting to file or using the --log option.

No equivalent in the YAML Configuration file.

  • Long-Form : --dump-remotes
  • Short-Form : -r
  • Negative-Form : None.
  • Default : false

Version

Displays the current version number then terminates. All other options will be ignored.

No equivalent in the YAML Configuration file.

  • Long-Form : --version
  • Short-Form : -v
  • Negative-Form : None.
  • Default : false

Help

Displays a brief help text listing syntax and availiable switches then terminates. All other options will be ignored.

No equivalent in the YAML Configuration file.

  • Long-Form : --help
  • Short-Form : -h
  • Negative-Form : None.
  • Default : false

Contribute to the Development

Contributing

The source code for update_repo is freely available on my Github pages, under the MIT license.

If you wish to help in any way then :

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

For full information on how to contribute to the development of this Gem or the Website, please see the Development section on the projects Github repository.

License

The gem is available as open source under the terms of the MIT License, see the file LICENSE.txt, also reproduced below :

        
          The MIT License (MIT)

          Copyright (c) 2016 Grant Ramsay

          Permission is hereby granted, free of charge, to any person obtaining a copy
          of this software and associated documentation files (the "Software"), to deal
          in the Software without restriction, including without limitation the rights
          to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
          copies of the Software, and to permit persons to whom the Software is
          furnished to do so, subject to the following conditions:

          The above copyright notice and this permission notice shall be included in
          all copies or substantial portions of the Software.

          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
          IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
          FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
          AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
          LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
          OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
          THE SOFTWARE.