thehipbot/hermes

Code Repository Manager

Hermes - Messenger of the Version Control Gods

Hermes allows you to manage your git repositories from the command line

NOTE: This project is a blatant ripoff of this project, bitcar, created by a friend and former colleague. I decided to create hermes because I wasn't a fan of the node dependency with bitcar and wanted additional features.

OTHER NOTE: Currently the project is still in the very early stages of development, so, although some features work, there's still plenty more to come and there is no guarantee of backwards compatibility until the project reaches the v1.0.0 mark.

Table of Contents

• Installation
• Setup
• Configuration
  • Example File
• Usage
  • Root/Get Command
  • Alias Command
  • Repository Commands
    • Repository Rm Command
  • Remote Commands
    • Remote Add Command
    • Remote Refresh Command
  • Setup Command
  • Version Command
• Contributing Guidlines

---

Installation

As the project is still in beta stages of development, it has not been distributed, and is only available to install from source. To install hermes, you must then have go setup with your GOPATH bin in your shell PATH. Once you have this you can install by running

go get -u github.com/TheHipbot/hermes
hermes -h

Setup

Once you have hermes installed, you must setup the hermes config directory and add an alias to you shell profile.

To create the config directory, run the following:

hermes setup

And you must add the hermes alias to your shell profile (e.g. $HOME/.bash_profile, .$HOME/.profile, etc):

cat >> ~/.bash_profile
if which hermes > /dev/null; then
    eval "$(hermes alias)"
fi

The above command will expect you to enter in the shell script text then end the command by hitting <CTRL+D>.

Configuration

Hermes supports yaml configuration files stored in either of these two locations on the system:

$HOME/.hermes.yml
/etc/hermes/.hermes.yml

Here is a list of the current supported config keys and values along with their use:

• repo_path (default: $HOME/hermes-repos/) - tells hermes where to clone repos to on your system. From this base path, repos will be stored similar to the go get tool. For example hermes will store itself in ${repo_path}/github.com/TheHipbot/hermes
• config_path (default: $HOME/.hermes/) - the directory where hermes will store configuration files such as its internal cache and the hermes target file. NOTE: you will want to set this in your hermes configuration file BEFORE you run hermes setup since that command will create the config folder.
• target_file (default: .hermes_target) - after running the hermes command, if there is a valid target (e.g. repo that you have cloned or want to jump to), hermes writes out the full path into the hermes target file. From there, the alias in your shell profile will read this, jump to the directory and then remove the target file. NOTE: target_file only specifies the file name, the file will be created in the config_path. if you change the target file after setting the hermes alias, you would need to open a new terminal session or re-source your profile file for the alias to realize the change
• cache_file (default: cache.json) - hermes stores a cache of repos it is aware of to allow for tab completion and prompts. this will be in json format. NOTE: cache_file only specifies the file name, the file will be created in the config_path
• alias_name (default: hermes) - the name of the alias function which calls through to the hermes binary. this will be the command you run when using hermes.
• credentials_type (default: none) - the type of storage which hermes user to store user provided credentials, supported types described below
  • none - this will not store the credentials at all, any time a call is made that requires authentication credentials must be passed into hermes
  • file - this is the default type and will store provided credentials in yaml file in plaintext NOTE: this is by no means a secure solution and its recommended not to use this in conjunction with usernames and passwords
• credentials_file (default: credentials.yml) - when using the file credential type, this is the filename in the config directory in which the credentials will be stored

Example .hermes.yml File

repo_path: /Users/jeremychambers/test-repos/
config_path: /Users/jeremychambers/.hermes-config/
cache_file: cached-repos.json
target_file: .hermes_target_file
alias_name: hit
credentials_type: file
credentials_file: my_credentials.yml

Usage

Root / Get Command

hermes [REPO] or hermes get [REPO]

Running the hermes command without any subcommands or with the get subcommand are synonymous. The command is used to jump to a repo in the hermes cache or pull down a repo then jump to its new location.

args - the expected arguments are a full repo path in this format: [remote address]/[project or user]/[repo nam] (e.g. github.com/TheHipbot/hermes) to clone a new repo, or a string to conduct a contains search on the repos in the hermes cache

When run, the following actions happen in order:

1. The hermes cache file is read in and then all repos are searched to see if they contain the text given as args
2. Based on the results of the search, 1 of 3 things will happen
   • If the search turns up a single result from the cache, hermes will set the target to the path of that repo and exit so the alias can move you to the directory
   • If the search turns up no results, hermes assumes this is a new repo and will attempt to clone it. If the clone is successful, the repo is added to the cache and the target is set to the new repo
   • If there are multiple results, the user is prompted to select a repo from the results. Once a repo is selected, hermes will continue with that repo.
3. Assuming the command has executed successfully a target path should be written to the target file. Hermes will exit 0 and the alias (assuming it has been setup) will read the path from the file, move the current working directory to that target directory, remove the target file and exit.

Alias Command

hermes alias

This command is meant only to provide the alias for a terminal session so it should be added to a shell profile, but not used otherwise. It writes to stdout a bash function which runs the hermes binary with the given args, then if a target file was written, it read the content as a directory to cd into. This is necessary because it is the only way which hermes can move the shell session's current working directory.

Remote Commands

hermes remote [SUBCOMMAND] [FLAGS] [ARGS]

This group of commands are used for managing remote git servers which hermes should track against. Remotes that have been added will be queried for repoistories to which the user has access. This repositories will be added to the cache file along with information on the remote itself.

Flags (Global to all remote commands)

-a, --all

When adding or refreshing a remote, this will index all repos available to the user (as opposed to starred or user owned repos which is the default depending on remote) if that option is available for the remote.

-p, --protocol

When adding a remote, you can add the protocol flag followed by a valid protocol (http, https, or ssh) inline with the remote command. If no protocol is present, the user will be prompted for a protocol.

Remote Add Command

hermes remote add [FLAGS] [REMOTE URL]

This command is used to add new git remotes to your hermes cache to use for searching and managing repositories. Once you run the command with a valid remote url, you will be prompted for which type of remote it is, your credentials to that remote, and which repository access protocol you would prefer. Adding a remote that already exists will act as a refresh to the remote, in this case any new values provided for protocol will be update in the cache and

Currently supported types of remotes:

• GitHub
• Gitlab

Currently supported protocols:

• http(s)
• ssh

Flags

--token

When adding a remote, you can add the token flag to provide an auth token inline to the command, which will then replace any existing entry for the token in the credentials storer. If authentication is not successful, user will be prompted for a new token.

-t, --type

When adding a remote, you can specify the type of remote inline to the command, valid options are github and gitlab.

Remote Refresh Command

hermes remote refresh [FLAGS]

The refresh command will attempt to "refresh" all currently tracked remotes by re-adding all repos of the remote. This will not affect existing repositories, but will add any new ones that have been created on the remote since the remote was first added or last refreshed.

Repository Commands

hermes repo [SUBCOMMAND] [FLAGS] [ARGS]

aliases: repository

This group of commands are used to manage repositories which hermes should track. Repositories will typically be added wholesale by remote, but can be added (soon) and removed individually from the cache and optionally from disk.

Repository Remove Command

hermes repo rm [FLAGS] [REPOSITORY NAME]

aliases: remove

The remove command will remove repositories from the hermes cache and optionally from the filesystem as well. Removing from the cache will keep the repository folder in the repo_dir but will remove it from the list of repos in the cache. If the repository still exists in the remote, refreshing the remote will add it back.

Flags

--hard

When removing a repository from the repository, adding the hard remove flag will also delete the directory for the repo that was cloned into the repo_dir if it exists. It will also recursively remove any empty parent directories up to the repo_dir.

Setup Command

hermes setup

Running hermes setup creates the config_path directory if specified in the .hermes.yml file or $HOME/.hermes by default. This ensures the directory is available for subsequent commands and should only be run once.

Version Command

hermes version

This command will output version information for the hermes binary you are executing.

hermes's Issues

Store Access key credentials somehow

Access keys can somewhat safely be stored locally since it is easy to revoke access, so when access keys are used to run against github or gitlab APIs these keys should be stored for future use.

Search should not be case-sensitive

Right now the Search function in the cache package is case-sensitive. It should not be.

Support different ports for remote host

If the git server is running on a different port other than 22, 443, or 80 then it should still be able to work with proper config

Add Version Command and Compile Version into Binary

There should be a hermes version command which will output the semantic version or the git commit if built from source to the user. This will require a semver for the project that is passed in on a build of the hermes binary.

Write Prettified JSON into Cache File

Not sure if its necessary, but there may be a need for the cache file having prettified JSON so it is somewhat human readable.

Update Short and Long Description for Hermes Root Command

in cmd/root.go the Short and Long description for the root command should be updated to reflect what it does.

Check for trailing slash in remote hosts and remove if present

When calling hermes remote add <host> if there is a trailing slash present, it will likely cause an error since the request formats have a preceding slash.

Repo folder should not be created for non-existent repos

Currently, if hermes command is used to get a repo that does not exist there is an attempted clone which creates the folder in the repos folder, and there is a cache entry made for the non-existent repo. Instead clone can be attempted but if it fails then folder is removed and no cache entry created. Either that or we first test if the repo exists before doing any work.

Running `get` on a repo name with a remote already in the cache but non-existent or non-cached repo errors

Running a hermes [get] on a repo name where the remote exists in the cache, but the repo doesn't causes an error.

Setup Mockgen for Test Mocks and Refactor Tests to Use It

Writing mocks for each test is tedious, setup mockgen to create the necessary mocks (preferably using comments in the files), refactor the tests to use the generated mocks, and create a make target in the Makefile to re-generate mocks

Create CI Pipeline for Project

The project needs a pipeline which can test the project and eventually deploy binaries.

Add support for alias command

Add an alias key to viper which has a default of hermes then use this value as an input to the aliasTemplate for the bash function name. This will allow the user to set an alias for hermes which they can call.

Allow for username and password credentials to remote

Create Functional Tests for Project and Clean Up Some Existing Unit Tests

Right now some unit tests act more as integration tests (hermes get tests for example will actually clone repos), these should be refactored to use mocks for unit tests and integration tests should be created which will run against built binaries.

Remove dependency on go-git

Although it is nice to have everything in go, including git itself, it has made things like pulling repos via SSH more difficult than it should be (this still only works if your SSH key doesn't require a password). At least for the time being, this will be removed in favor of calling through to the git binary on the users system. Perhaps in the future it will be offered again as a option for building the bin.

Configure tool for github user repos

Add ability to configure tool to add github user and add all repos of user to cache

Stale Stored Credentials Throw Error

Trying to run a hermes remote add (or soon a hermes remote refresh) on a remote that already has a credential stored, but the credential is no longer valid will throw an error. Instead a message should be logged and the user should be prompted for an updated credential.

Better logging / output strategy

Currently, output to the user is inconsistent. A proper logging strategy should be implemented and possibly even provide configuration options for it to users.

Come up with better cleanup strategy for cmd package

Currently the cleanup strategy (e.g. closing the cache file or credentials file before completing the command) is ad-hoc and across multiple files. A better cleanup strategy should be centralized and employed.

Cloned repos should be tracking master against remote

When git-go clones a repo it does not track the local master against the remote master. Add code to modify .git/config to add tracking for branch. This may be better as a PR to go-git.

Add Remove command

Add a command hermes rm <repo> which would remove the given repo from the cache. Also add a --hard command which would delete the repo from the file system if it exists. There is already a remove command in the cache package, all you would need to do is add a remove command to the root cobra command and call through.

Add Gitlab Support

Add support for gitlab remotes by creating a new driver for gitlab. The gitlab API is very similar to that of GitHub so there are pieces of that code (currently in remote/github.go) that should be reusable. Namely the getHelperRepo function and the parseLinkHeader function. This may also require some refactoring for the creators signature, since gitlab not only has the public gitlab site, but also gitlab can be self hosted at different domains.

Ensure alphabetical ordering on cache searches

With the current implementation, there is no guarantee of ordering on repos retrieved from a search of the cache. Results should be presented to the user in alphabetical order.

Cache Cloned Repos

Any newly cloned repo should be added to the cache.

Adding the same remote again duplicates cache entries for the repos

When running hermes remote add on a remote which is already present in the cache with repos, then cache entries will be duplicated for the repos.

Calling `hermes get` on a full repo name doesn't work unless repo is in cache

The desired behavior if calling a hermes get on a full repo name (e.g. remote/group/repo) if that repo is not in cache is to clone it down and add it to the cache (assuming the correct permissions are in place). Right now it errors because the repo is added to the cache but with some missing data (like the clone URLs)

Make remote add input take a valid url

for consistency, remote add should be a url and it should be added to the repository by the hostname only.

Support different users for SSH

Current implementation for SSH assumes the user is git, this should be able to be set by the user.

Refactor remote package to use client libraries

Find a suitable client library for each supported remote type and refactor the code to use the client library for the GetRepos operations.

Support multiple cloning protocols

Hermes assumes that the clone url is using https protocol, but should have support for ssh and probably even http. This protocol should be in the config and set at the remote level. Possibly something like this:

remotes: 
  github.com:
    protocol: ssh

Change config files to use .config folder

Hermes should prefer storing all configuration files (.hermes.yml and .hermes/*) in a .config folder as opposed to living in the home folder.

Clean up Prompt Package to Expose Only the Factory and Prompt Interfaces

The prompt package is doing too much. Functions like CreateDriverSelectPrompt and CreateRepoSelectPrompt should be moved out to where the prompt is needed along with the labels and templates. This will make it more generic and removed the necessity to create yet another function for every prompt. There should also probably be a NewPrompter or NewFactory function exposed so that the user can call the factory directly.

Add edit command to open repo in a text editor or IDE

Add a command hermes edit <repo or search> or a flag hermes -e <repo or search> which would clone and/or jump to a repo but also open the project in a text editor. The editor should be set in the hermes config, or default to the $EDITOR environment variable.

Add remote refresh command

The command hermes remote refresh should use stored credentials when available (or prompt for them) and should add any new repos since the remote was added or since the last refresh. This should allow for an argument of the remote you would like to refresh or if no argument is given refresh all.

Add support for multiple repo directories

Currently hermes has a single repo_path configured in the .hermes.yml or by default being $HOME/hermes-repos/. Instead hermes should support having multiple repo paths for use cases such as Golang projects (which should be stored in $GOPATH/src) whereas you may want to store non-go repos elsewhere. I think that in the case where hermes is cloning a repo and unsure which repo_path to clone it to, the user should be prompted to select from the configured paths, but would be open to suggestions. I have also thought about adding support for .hermesrc files that could live in the target project which could specify an ideal repo_path but prompting would be a good starting point. I see a couple parts to this which could be done incrementally:

• Modify the config to have a repo_paths key (or something of the like) which would have a list of key / value pairs as element where the key would be a user defined name for the path (e.g. go) , and the value being the path to store those directories. I think we can retain backwards compatibility here in the case that the repo_path is set it would take precedence.

• In the case that there are multiple repo paths configured and hermes is attempting a clone, the user should be prompted as to which to use and this path should be stored in the cache Add call.

• Optionally support could be added for a default_repo config where if a -f like flag were added to a get command, the user would not be prompted and hermes would proceed with the default_repo

Docs for remote add command

Add docs for hermes remote add command to README.md

Create cache of non-cloned repos

When a new remote or user is added all repos from the user or remote should be added to the cache for auto complete or user prompt