update_repo
A Simple Gem to keep multiple locally-cloned Git Repositories up to date.
This is the conversion to a Gem of one of my standalone Ruby scripts. Still a work in progress but the required base functionality is there.
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: 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.
Installation
Pre-requirements
It goes without saying that at the very least a working copy of both Git
(version 1.8.5 or greater, the script will not run with an older version) and Ruby
(version 1.9.3 and newer) need to be installed on your machine. Also, the script has currently only been tested under Linux, not windows.
Install this from the shell prompt as you would any other Ruby Gem
$ gem install update_repo
Usage
Quick start
Create a YAML-formatted configuration file .updaterepo
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
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 and the Website for more information.
This file should be located in the users home directory (~/.updaterepo
).
Run the script :
$ update_repo
Configuration
The below is a summary of the most common configuration options, see the Website for complete details and usage.
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 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
, defaults to FALSE (optional)
log: true
timestamp:
- timestamp the output files instead of overwriting them, defaults to FALSE (optional)
timestamp: true
verbose:
- display the output of the git command for each repo, defaults to FALSE (optional)
verbose: true
quiet:
- no output at all, not even the header and footer, defaults to FALSE (optional)
quiet: true
Command line switches
Options are not required. If none are specified then the program will read from the standard configuration file (~/.updaterepo) and automatically update the specified Repositories. Command line options will take preference over those specified in the configuration file. Again, see the Website for complete details and usage.
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.
-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
-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
To-Do
Add functionality, not in any specific order :
- Either add an option 'variants' or similar to allow non-standard git pull commands (eg Ubuntu kernel), or update the 'exceptions' option to do same.
- Add command line option to specify an alternate config file.
- Add ability to specify a new directory (containing Git repos) to search from the command line, and optionally save this to the standard configuration.
- Add new repo from the command line that will be cloned to the default repo directory and then updated as usual. Extra flag added for "add only, clone later" for offline use.
- Add flag for 'default' repo directory (or another specific directory - if it does not already exist it will be created and added to the standard list) which will be used for new additions.
- Add option to only display a (text) tree of the discovered git repositories, not updating them.
- Add Import & Export functionality :
- ability to export a text dump of each repo location and remote as a CSV file.
[DONE]
- re-import the above dump on a different machine or after reinstall. Modify the '--prune' command to apply to this function also, removing the required number of directory levels before importing.
- ability to export a text dump of each repo location and remote as a CSV file.
- Add option to use alternative git command if required, either globally or on a case-by-case basis (see also comments on 'variants' above). Currently the script just uses a blanket
git pull
command on all repositories. - Implement the option
--log-local
to put log file into the local directory. - Add option to specify a completely different directory for the log file other than the 2 current (planned, local not yet implemented) options (home dir and local)
- Document configuration file format and options.
[IN PROGRESS]
Internal Changes and refactoring :
- Add testing!
- Error checking and reporting for the git processes
[IN PROGRESS]
- Improve error-checking and recovery while parsing the configuration file
- Ignore and report invalid or missing directories
- Add more failure cases, there may be more git errors than "fatal:" or "error:"
- Retry for connection issues etc (config setting).
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests (or simply rake
). You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
Run rake
to run the RSpec tests, which also runs RuboCop
, Reek
and inch --pedantic
too.
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Please note - This Gem currently aims to pass 100% on RuboCop, Reek and Inch-CI (on pedantic mode), so all pull requests should do likewise. Ask for guidance if needed.
Running rake
will automatically test all 3 of those along with the RSpec tests.
Versioning
This Gem aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.
Of course, currently we have not even reached version 1, so leave off the version requirement completely. Expect any and all of the API and interface to change!
License
The gem is available as open source under the terms of the MIT License.