RubyGit

THIS PROJECT IS A WORK IN PROGRESS AND IS NOT USEFUL IN ITS CURRENT STATE

Git Is Hard™ but it doesn't have to be that way. Git has this reputation because it has an underlying model that is more complex than other popular revision control systems such as CVS or Subversion. To make matters worse, the git command line is vast, inconsistently implemented, and does not have a clear mapping between the command-line actions and Git's underlying model.

Because of this complexity, beginners tend to memorize a few git commands in order to get by with a simple workflow without really understanding how Git works and the rich set of features it offers.

The RubyGit module provides a Ruby API that is an object-oriented wrapper around the git command line. It is intended to make automating both simple and complex Git interactions easier. To accomplish this, it ties each action you can do with git to the type of object that action operates on.

There are three main objects in RubyGit:

• WorkingTree: The directory tree of actual checked out files. The working tree normally contains the contents of the HEAD commit’s tree, plus any local changes that you have made but not yet committed.
• Index: The index is used as a staging area between your working tree and your repository. You can use the index to build up a set of changes that you want to commit together. When you create a commit, what is committed is what is currently in the index, not what is in your working directory.
• Repository: The repository stores the files in a project, their history, and other meta data like commit information, tags, and branches.

The RubyGit Class Diagram shows the main abstractions in RubyGit, how they are related, and what actions each can perform.

Add this line to your application's Gemfile:

gem 'ruby_git'

And then execute:

$ bundle install

Or install it directly from the command line:

$ gem install ruby_git

To configure RubyGit:

RubyGit.git.path = '/usr/local/bin/git'

# Returns the user set path or searches for 'git' in ENV['PATH']
RubyGit.git.path #=> '/usr/local/bin/git'
RubyGit.git.version #=> [2,28,0]

To work with an existing WorkingTree:

working_tree = RubyGit.open(working_tree_path)
working_tree.append_to_file('README.md', 'New line in README.md')
working_tree.add('README.md')
working_tree.commit('Add a line to the README.md')
working_tree.push

To create a new WorkingTree:

working_tree = RubyGit.init(working_tree_path)
working_tree.write_to_file('README.md', '# My New Project')
working_tree.add('README.md')
working_tree.repository.add_remote(remote_name: 'origin', url: 'https://github.com/jcouball/test', default_branch: 'main')
working_tree.push(remote_name: 'origin')

To tell what version of Git is being used:

puts RubyGit.git_version

The full API is documented in the RubyGit YARD documentation.

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake to run tests, static analysis, and build the gem.

For experimentation, you can also run bin/console for an interactive (IRB) prompt that automatically requires ruby_git.

Bug reports and pull requests are welcome on GitHub at https://github.com/main-branch/ruby_git.

All commit messages must follow the Conventional Commits standard. This helps us maintain a clear and structured commit history, automate versioning, and generate changelogs effectively.

To ensure compliance, this project includes:

• A git commit-msg hook that validates your commit messages before they are accepted.

  To activate the hook, you must have node installed and run npm install.

• A GitHub Actions workflow that will enforce the Conventional Commit standard as part of the continuous integration pipeline.

  Any commit message that does not conform to the Conventional Commits standard will cause the workflow to fail and not allow the PR to be merged.

All pull requests must be merged using rebase merges. This ensures that commit messages from the feature branch are preserved in the release branch, keeping the history clean and meaningful.