gitt 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0299e137ff3816d95cdc4a92ccc4af9a47bacb19756e49ce4c3ad046d7dfe701'
+  data.tar.gz: 39829d79861e88f5e6d7af24f34202d518dbbc8faffe212503e340766a891342
+SHA512:
+  metadata.gz: 932f1cd9202c325642f1e829ec7a7baffe5d3d1d364db1f7c3e807f0f4081998dbe0f0e9413d97d87241646595ed838cb72738164c89391be439ad83f1b647d2
+  data.tar.gz: f00e865926dbc62c1776fb6ecdbf62e31037b20259964c7c27985642d6693da1f7c16d0457be1ff605d7c51e2c0db3699b9c44626e95b1b334736a4370ffe9ff

data/LICENSE.adoc

@@ -0,0 +1,134 @@
+= Hippocratic License
+
+Version: 2.1.0.
+
+Purpose. The purpose of this License is for the Licensor named above to
+permit the Licensee (as defined below) broad permission, if consistent
+with Human Rights Laws and Human Rights Principles (as each is defined
+below), to use and work with the Software (as defined below) within the
+full scope of Licensor’s copyright and patent rights, if any, in the
+Software, while ensuring attribution and protecting the Licensor from
+liability.
+
+Permission and Conditions. The Licensor grants permission by this
+license ("License"), free of charge, to the extent of Licensor’s
+rights under applicable copyright and patent law, to any person or
+entity (the "Licensee") obtaining a copy of this software and
+associated documentation files (the "Software"), to do everything with
+the Software that would otherwise infringe (i) the Licensor’s copyright
+in the Software or (ii) any patent claims to the Software that the
+Licensor can license or becomes able to license, subject to all of the
+following terms and conditions:
+
+* Acceptance. This License is automatically offered to every person and
+entity subject to its terms and conditions. Licensee accepts this
+License and agrees to its terms and conditions by taking any action with
+the Software that, absent this License, would infringe any intellectual
+property right held by Licensor.
+* Notice. Licensee must ensure that everyone who gets a copy of any part
+of this Software from Licensee, with or without changes, also receives
+the License and the above copyright notice (and if included by the
+Licensor, patent, trademark and attribution notice). Licensee must cause
+any modified versions of the Software to carry prominent notices stating
+that Licensee changed the Software. For clarity, although Licensee is
+free to create modifications of the Software and distribute only the
+modified portion created by Licensee with additional or different terms,
+the portion of the Software not modified must be distributed pursuant to
+this License. If anyone notifies Licensee in writing that Licensee has
+not complied with this Notice section, Licensee can keep this License by
+taking all practical steps to comply within 30 days after the notice. If
+Licensee does not do so, Licensee’s License (and all rights licensed
+hereunder) shall end immediately.
+* Compliance with Human Rights Principles and Human Rights Laws.
+[arabic]
+. Human Rights Principles.
+[loweralpha]
+.. Licensee is advised to consult the articles of the United Nations
+Universal Declaration of Human Rights and the United Nations Global
+Compact that define recognized principles of international human rights
+(the "Human Rights Principles"). Licensee shall use the Software in a
+manner consistent with Human Rights Principles.
+.. Unless the Licensor and Licensee agree otherwise, any dispute,
+controversy, or claim arising out of or relating to (i) Section 1(a)
+regarding Human Rights Principles, including the breach of Section 1(a),
+termination of this License for breach of the Human Rights Principles,
+or invalidity of Section 1(a) or (ii) a determination of whether any Law
+is consistent or in conflict with Human Rights Principles pursuant to
+Section 2, below, shall be settled by arbitration in accordance with the
+Hague Rules on Business and Human Rights Arbitration (the "Rules");
+provided, however, that Licensee may elect not to participate in such
+arbitration, in which event this License (and all rights licensed
+hereunder) shall end immediately. The number of arbitrators shall be one
+unless the Rules require otherwise.
++
+Unless both the Licensor and Licensee agree to the contrary: (1) All
+documents and information concerning the arbitration shall be public and
+may be disclosed by any party; (2) The repository referred to under
+Article 43 of the Rules shall make available to the public in a timely
+manner all documents concerning the arbitration which are communicated
+to it, including all submissions of the parties, all evidence admitted
+into the record of the proceedings, all transcripts or other recordings
+of hearings and all orders, decisions and awards of the arbitral
+tribunal, subject only to the arbitral tribunal’s powers to take such
+measures as may be necessary to safeguard the integrity of the arbitral
+process pursuant to Articles 18, 33, 41 and 42 of the Rules; and (3)
+Article 26(6) of the Rules shall not apply.
+. Human Rights Laws. The Software shall not be used by any person or
+entity for any systems, activities, or other uses that violate any Human
+Rights Laws. "Human Rights Laws" means any applicable laws,
+regulations, or rules (collectively, "Laws") that protect human,
+civil, labor, privacy, political, environmental, security, economic, due
+process, or similar rights; provided, however, that such Laws are
+consistent and not in conflict with Human Rights Principles (a dispute
+over the consistency or a conflict between Laws and Human Rights
+Principles shall be determined by arbitration as stated above). Where
+the Human Rights Laws of more than one jurisdiction are applicable or in
+conflict with respect to the use of the Software, the Human Rights Laws
+that are most protective of the individuals or groups harmed shall
+apply.
+. Indemnity. Licensee shall hold harmless and indemnify Licensor (and
+any other contributor) against all losses, damages, liabilities,
+deficiencies, claims, actions, judgments, settlements, interest, awards,
+penalties, fines, costs, or expenses of whatever kind, including
+Licensor’s reasonable attorneys’ fees, arising out of or relating to
+Licensee’s use of the Software in violation of Human Rights Laws or
+Human Rights Principles.
+* Failure to Comply. Any failure of Licensee to act according to the
+terms and conditions of this License is both a breach of the License and
+an infringement of the intellectual property rights of the Licensor
+(subject to exceptions under Laws, e.g., fair use). In the event of a
+breach or infringement, the terms and conditions of this License may be
+enforced by Licensor under the Laws of any jurisdiction to which
+Licensee is subject. Licensee also agrees that the Licensor may enforce
+the terms and conditions of this License against Licensee through
+specific performance (or similar remedy under Laws) to the extent
+permitted by Laws. For clarity, except in the event of a breach of this
+License, infringement, or as otherwise stated in this License, Licensor
+may not terminate this License with Licensee.
+* Enforceability and Interpretation. If any term or provision of this
+License is determined to be invalid, illegal, or unenforceable by a
+court of competent jurisdiction, then such invalidity, illegality, or
+unenforceability shall not affect any other term or provision of this
+License or invalidate or render unenforceable such term or provision in
+any other jurisdiction; provided, however, subject to a court
+modification pursuant to the immediately following sentence, if any term
+or provision of this License pertaining to Human Rights Laws or Human
+Rights Principles is deemed invalid, illegal, or unenforceable against
+Licensee by a court of competent jurisdiction, all rights in the
+Software granted to Licensee shall be deemed null and void as between
+Licensor and Licensee. Upon a determination that any term or provision
+is invalid, illegal, or unenforceable, to the extent permitted by Laws,
+the court may modify this License to affect the original purpose that
+the Software be used in compliance with Human Rights Principles and
+Human Rights Laws as closely as possible. The language in this License
+shall be interpreted as to its fair meaning and not strictly for or
+against any party.
+* Disclaimer. TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES
+"AS IS," WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR AND
+ANY OTHER CONTRIBUTOR SHALL NOT BE LIABLE TO ANYONE FOR ANY DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+OR THIS LICENSE, UNDER ANY KIND OF LEGAL CLAIM.
+
+This Hippocratic License is an link:https://ethicalsource.dev[Ethical Source license] and is offered
+for use by licensors and licensees at their own risk, on an "AS IS" basis, and with no warranties
+express or implied, to the maximum extent permitted by Laws.

data/README.adoc

@@ -0,0 +1,299 @@
+:toc: macro
+:toclevels: 5
+:figure-caption!:
+
+:git_link: link:https://git-scm.com[Git]
+:struct_link: link:https://www.alchemists.io/articles/ruby_structs[Struct]
+
+= Gitt
+
+Provides a monadic Object API to the {git_link} CLI. This project is also an extraction of work originally implemented within the following projects:
+
+* link:https://www.alchemists.io/projects/git-lint[Git Lint]
+* link:https://www.alchemists.io/projects/milestoner[Milestoner]
+* link:https://www.alchemists.io/projects/rubysmith[Rubysmith]
+
+If you are looking for alternatives within this space, you might find the following gems of benefit too:
+
+* link:https://github.com/ruby-git/ruby-git[Ruby Git]
+* link:https://github.com/libgit2/rugged[Rugged]
+
+toc::[]
+
+== Features
+
+* Wraps all Git commands with additional enhancements to improve your working experience.
+* Answers link:https://dry-rb.org/gems/dry-monads[monads] so you can pipe commands together for more powerful and complex workflows.
+
+== Requirements
+
+. {git_link}
+. link:https://www.ruby-lang.org[Ruby]
+
+== Setup
+
+To set up the project, run:
+
+[source,bash]
+----
+bin/setup
+----
+
+== Usage
+
+At a high level, this project provides a centralized Object API via a single object: `Repository`. Example:
+
+[source,ruby]
+----
+git = Gitt::Repository.new
+
+git.branch          # Equivalent to `git branch <arguments>`.
+git.branch_default  # Answers default branch.
+git.branch_name     # Answers current branch.
+git.call            # Allows you to run any Git command.
+git.commits         # Answers commit records.
+git.config          # Equivalent to `git config <arguments>`.
+git.exist?          # Answers if current directory is a Git repository or not.
+git.get             # Equivalent to `git config get`.
+git.log             # Equivalent to `git log <arguments>`.
+git.origin?         # Answers if repository has an origin or not.
+git.set             # Equivalent to `get config set`.
+git.tag             # Equivalent to `git tag <arguments>`.
+git.tag?            # Answers if local or remote tag exists.
+git.tag_create      # Create a new tag.
+git.tag_last        # Anwswers last tag created.
+git.tag_local?      # Answers if local tag exists?
+git.tag_parse       # Parses and answers a tag record.
+git.tag_remote?     # Answers if remote tag exists?
+git.tagged?         # Answers if the repository has any tags.
+git.tags_push       # Pushes local tags to remote git.
+git.uncommitted     # Parses a file and answers an unsaved commit message.
+----
+
+=== Commands
+
+Should you want to use individual commands instead of interacting with the `Repository` object, you
+can leverage any of the objects in the `Commands` namespace which -- at a minimum -- use the link:https://www.alchemists.io/articles/interactor_pattern[Command Pattern]. Here are the _select_ commands which are enhanced further:
+
+==== link:https://git-scm.com/docs/git-branch[Branch]
+
+Handles branches.
+
+[source,ruby]
+----
+branch = Gitt::Commands::Branch.new
+
+# Answers branch default (via Git `init.defaultBranch` configuration).
+branch.default  # Success "main"
+
+# Accepts any argument you'd send to `git branch`. Example:
+branch.call "--list"  # Success "  main\n"
+
+# Answers current branch
+branch.name  # Success "major"
+----
+
+==== link:https://git-scm.com/docs/git-config[Config]
+
+Handles global and local configurations.
+
+[source,ruby]
+----
+config = Gitt::Commands::Config.new
+
+# Accepts any argument you'd send to `git config`. Example:
+config.call "--get", "rebase.abbreviateCommands"  # Success "true\n"
+
+# Answers value for key with support for fallback value or block manipulation.
+config.get "user.name"                                     # Success "Brooke Kuhlmann"
+config.get "user.unknown", "fallback"                      # Success "fallback"
+config.get("user.unknown") { |value| value + "fallback" }  # "fallback"
+
+# Answers true or false if origin is defined.
+config.origin?                                             # true
+
+# Sets configuration key and value.
+config.set "user.demo", "test"                             # Success "test"
+----
+
+==== link:https://git-scm.com/docs/git-log[Log]
+
+Handles commit history.
+
+[source,ruby]
+----
+log = Gitt::Commands::Log.new
+
+log.call "--oneline", "-1"  # Success "5e21a9866827 Added documentation\n"
+----
+
+The `Log` class provides two other methods but they require a more detailed explanation. The first is `Log#all` which answers an array of commits (records) upon success and accepts the same arguments as given to `#call`.
+
+[source,ruby]
+----
+commit = log.all
+----
+
+The second, is:
+
+[source,ruby]
+----
+commit log.uncommitted ".git/COMMIT_EDITMSG"
+----
+
+The above will answer a single commit record. This is great for building a commit object from an unsaved commit message. The only disadvantage of this approach is that you will get template commits which are always stripped out by Git when processing a _saved_ commit.
+
+==== link:https://git-scm.com/docs/git-tag[Tag]
+
+Handles the tagging/versioning of commits.
+
+[source,ruby]
+----
+tag = Gitt::Commands::Tag.new
+
+# Accepts any argument you'd send to `git tag`.
+# Example: tag.call "--list"
+stdout, stderr, status = tag.call
+
+# Answers true or false base on whether local and remote tag exist.
+tag.exist? "0.1.0"
+
+# Answers last tag for git.
+tag.last
+
+# Answers if local tag exists.
+tag.local? "0.1.0"
+
+# Pushes tags to remote git.
+tag.push
+
+# Answers if remote tag exists.
+tag.remote? "0.1.0"
+
+# Answers true or false based on whether repository is tagged.
+tag.tagged?
+----
+
+=== Models
+
+In order to have access to rich data from the Git client, there are several models available to you.
+
+==== Commit
+
+An instance of `Gitt::Commits::Model` is what is answered back to when using `Gitt::Repository` via the `#commits` or `#uncommitted` methods. In each case, you'll either get an array of records, a single record, or a failure depending on the result. Here's an example of a single record:
+
+[source,ruby]
+----
+# #<struct Gitt::Commits::Model
+#  author_date_relative="2 days ago",
+#  author_email="demo@example.com",
+#  author_name="Demo User",
+#  body="Necessary to explain recent changes.\n",
+#  body_lines=["Necessary to explain recent changes."],
+#  body_paragraphs=["Necessary to explain recent changes."],
+#  message="Updated documentation with new functionality\n\nNecessary to explain recent changes.\n",
+#  sha="5e21a9866827bf5c68bd445ea01b3837a3936b45",
+#  subject="Updated documentation with new functionality",
+#  trailers=[],
+#  trailers_index=nil>
+----
+
+You get a {struct_link} with the following attributes:
+
+* `author_date_relative`: Stores the relative date of when the commit was made.
+* `author_email`: Stores the author email.
+* `author_name`: Stores the author name.
+* `body`: Stores the commit body which excludes the subject and leading space.
+* `body_lines`: Stores each line of the body in an array.
+* `body_paragraphs`: Stores each paragraph of the body as an array (i.e. broken by double new lines).
+* `message`: Stores the entire, raw, commit message (i.e. subject and body).
+* `sha`: Stores the commit SHA.
+* `subject`: Stores the commit subject.
+* `trailers`: Stores any commit trailers as an array of `GtiPlus::Trailers::Model` records.
+* `trailers_index`: Stores the starting index of trailers within the commit message.
+
+==== Tag
+
+An instance of `Gitt::Tags::Model` is what is answered back to when using `Gitt::Repository` via the `#tag_parse` method. Here's an example:
+
+[source,ruby]
+----
+# #<struct Gitt::Tags::Model
+#  author_date="Tue Dec 29 17:33:01 2020 -0700",
+#  author_email="demo@example.com",
+#  author_name="Demo User",
+#  body="- Added gem skeleton\n- Added RSpec dependnecy",
+#  sha="d041d07c29f97b5b06b3b2fd05fa1dd018c7da7c",
+#  subject="Version 0.1.0",
+#  version="0.1.0">
+----
+
+You get a {struct_link} with the following attributes:
+
+*  `author_date`: Stores author creation date.
+*  `author_email`: Stores author email.
+*  `author_name`: Store author name.
+*  `body`: Stores body of tag which can be sentences, multiple paragraphs, and/or signature information.
+*  `sha`: Stores the commit SHA for which this tag labels
+*  `subject`: Stores the subject.
+*  `version`: Stores the version.
+
+==== Trailer
+
+A trailer is nested within a commit record when trailer information exists. Example:
+
+[source,ruby]
+----
+#<struct Gitt::Commits::Trailers::Model key="Issue", delimiter=":", space=" ", value="123">
+----
+
+The attributes break down as follows:
+
+* `key`: Answers the key.
+* `delimiter`: Answers the delimiter which must be a colon but can be missing if invalid.
+* `space`: Answers either a space or an empty string with the former being invalid.
+* `value`: Answers the value associated with the key.
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/gitt
+cd gitt
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
+== Tests
+
+To test, run:
+
+[source,bash]
+----
+bundle exec rake
+----
+
+== link:https://www.alchemists.io/policies/license[License]
+
+== link:https://www.alchemists.io/policies/security[Security]
+
+== link:https://www.alchemists.io/policies/code_of_conduct[Code of Conduct]
+
+== link:https://www.alchemists.io/policies/contributions[Contributions]
+
+== link:https://www.alchemists.io/projects/gitt/versions[Versions]
+
+== link:https://www.alchemists.io/community[Community]
+
+== Credits
+
+* Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/gitt.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "gitt"
+  spec.version = "1.0.0"
+  spec.authors = ["Brooke Kuhlmann"]
+  spec.email = ["brooke@alchemists.io"]
+  spec.homepage = "https://www.alchemists.io/projects/gitt"
+  spec.summary = "Provides a monadic Object API wrapper around the Git CLI."
+  spec.license = "Hippocratic-2.1"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/bkuhlmann/gitt/issues",
+    "changelog_uri" => "https://www.alchemists.io/projects/gitt/versions",
+    "documentation_uri" => "https://www.alchemists.io/projects/gitt",
+    "funding_uri" => "https://github.com/sponsors/bkuhlmann",
+    "label" => "Gitt",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/bkuhlmann/gitt"
+  }
+
+  spec.signing_key = Gem.default_key_path
+  spec.cert_chain = [Gem.default_cert_path]
+
+  spec.required_ruby_version = "~> 3.2"
+  spec.add_dependency "dry-monads", "~> 1.6"
+  spec.add_dependency "refinements", "~> 10.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

data/lib/gitt/commands/branch.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Gitt
+  module Commands
+    # A Git branch command wrapper.
+    class Branch
+      def initialize shell: SHELL
+        @shell = shell
+      end
+
+      def default
+        shell.call("config", "init.defaultBranch")
+             .fmap(&:chomp)
+             .fmap { |name| name.empty? ? "main" : name }
+      end
+
+      def call(*arguments) = shell.call "branch", *arguments
+
+      def name = shell.call("rev-parse", "--abbrev-ref", "HEAD").fmap(&:chomp)
+
+      private
+
+      attr_reader :shell
+    end
+  end
+end

data/lib/gitt/commands/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Gitt
+  module Commands
+    # A Git config command wrapper.
+    class Config
+      include Dry::Monads[:result]
+
+      def initialize shell: SHELL
+        @shell = shell
+      end
+
+      def call(*arguments) = shell.call "config", *arguments
+
+      def get key, fallback = "", *arguments
+        call(*arguments, "--get", key).fmap(&:chomp)
+                                      .or do |error|
+                                        block_given? ? yield(error) : Success(fallback)
+                                      end
+      end
+
+      def origin? = !get("remote.origin.url").value_or(EMPTY_STRING).empty?
+
+      def set(key, value, *arguments) = call(*arguments, "--add", key, value).fmap { value }
+
+      private
+
+      attr_reader :shell
+    end
+  end
+end

data/lib/gitt/commands/log.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Gitt
+  module Commands
+    # A Git log command wrapper.
+    class Log
+      include Dry::Monads[:result]
+
+      KEY_MAP = {
+        author_email: "%ae",
+        author_name: "%an",
+        authored_at: "%at",
+        authored_relative_at: "%ar",
+        body: "%b",
+        committed_at: "%ct",
+        committed_relative_at: "%cr",
+        committer_email: "%ce",
+        committer_name: "%cn",
+        raw: "%B",
+        sha: "%H",
+        signature: "%G?",
+        subject: "%s",
+        trailers: "%(trailers)"
+      }.freeze
+
+      def initialize shell: SHELL, key_map: KEY_MAP, parser: Parsers::Commit
+        @shell = shell
+        @key_map = key_map
+        @parser = parser
+      end
+
+      def call(*arguments) = shell.call "log", *arguments
+
+      def index *arguments
+        arguments.prepend(pretty_format)
+                 .then { |pretty_format| call(*pretty_format) }
+                 .fmap { |content| String(content).scrub("?").split %("\n") }
+                 .fmap { |entries| build_records entries }
+      end
+
+      def uncommitted path
+        return Failure %(Invalid commit message path: "#{path}".) unless path.exist?
+
+        shell.call("mktree")
+             .bind { |raw_sha| shell.call "commit-tree", "-F", path.to_s, raw_sha.chomp }
+             .bind { |sha| index "-1", sha.chomp }
+             .fmap(&:first)
+      end
+
+      private
+
+      attr_reader :shell, :key_map, :parser
+
+      def pretty_format
+        key_map.reduce("") { |string, (key, value)| string + "<#{key}>#{value}</#{key}>%n" }
+               .then { |structure| %(--pretty=format:"#{structure}") }
+      end
+
+      def build_records(entries) = entries.map { |entry| parser.call(entry) }
+    end
+  end
+end