Skip to content

Latest commit

 

History

History
359 lines (255 loc) · 11.2 KB

README.md

File metadata and controls

359 lines (255 loc) · 11.2 KB
Raw

License: MIT v3


go-git-mob

A golang port of the nodejs git-mob tool, go-git-mob assists with managing co-authors when mob programming.
README · CHANGELOG . CONTRIBUTING
Report Bug · Request Feature

Table of contents

About the project

git-mob helps manage git co-authors when collaborating in real-time.

As the original authors of the node git-mob tool wrote:

Documenting code collaboration

When we work together, we should document that. It’s more than just giving credit to others, it’s also informing everyone about who was responsible for introducing changes to a codebase. Keeping a clear record of your work has lasting value - ever stumbled on an old commit only to be left with unanswered questions? In addition to explaining in your commits why a change was introduced, it also helps to document who implemented the change in case there needs to be a follow up.

Why port the nodejs version to Golang?

People working with nodejs commonly use a version manager like nodenv, nvm, or asdf to manage several versions of nodejs side-by-side.

These tools install global packages per node version which means you have to install the node git-mob plugin once per node version.

In contrast Golang offers the ability to build source code into single-file executables which truly install globally, independent of any versioning tools.

A Golang version of git-mob simplifies the install and update story making this plugin more manageable.

What about mob.sh?

Like the original nodejs git-mob plugin, this golang port tool differs from and complements mob.sh in two key ways:

  • whereas mob.sh detects co-authors from commit messages alone, git-mob and go-git-mob understand that not all co-authors have their hands on the keyboard each session.
  • whereas mob.sh squashes each feature branch into a single commit, git-mob and go-git-mob leave this decision up to you, complimenting your workflow by injecting conventional Co-authored-by: comments into each commit message through the use of a git prepare-commit-message hook.

Built with

Getting started

Install

⚠️ The install process changed in v0.6.0 If you have a version of go-git-mob older to v0.6.0 you must first uninstall the current version. See Uninstall for instructions.

go install

With a working golang installation at version >= 1.20 you can install or update with:

go install github.com/davidalpert/go-git-mob/cmd/git-mob@latest

Ensure that your path contains the GOPATH bin folder:

if [[ ":$PATH:" == *":$(go env GOPATH)/bin:"* ]]; then echo "your path is correctly set"; else echo "your path is missing $(go env GOPATH)/bin; please add it"; fi

Pre-compiled binaries

Visit the Releases page to find binary packages pre-compiled for a variety of GOOS and GOARCH combinations:

  1. Download an appropriate package for your GOOS and GOARCH;
  2. Unzip it and put the binary in your path;

Verify your installation

Confirm that git recognizes the git-mob plugin:

> git mob version
git-mob 0.5.1+f5536c2

Post-install steps

  1. Install helper plugins: [once per machine]

    git mob rehash

    • The rehash sub-command generates simple shell scripts to make the following git plugin helpers available:

      git mob-print
git mob-version
git solo
git suggest-coauthors

  2. Add some co-authors:

    git add-coauthor jd "Jane Doe" "jane@example.com"

  3. List available co-authors:

    git mob --list

  4. Initialize prepare-commit-msg hook script: [once per repository]

    git mob init

git-mob uses a configuration file called ~/.git-coauthors to store available coauthors by initials.

Add initials of the current mob to your prompt

Zsh with Powerlevel10k

  1. edit the p10k configuration file: 
    vi $POWERLEVEL9K_CONFIG_FILE
  2. search for the example prompt function: 
    prompt_example()
  3. create a similar custom p10k prompt function to generate a mob initials prompt segment: 
    # custom p10k prompt to print git mob member initials
function prompt_gitmob_members() {
  initials=$(git mob-print --initials 2> /dev/null)
  if [ ! -z "$initials" ]; then
    p10k segment -f 208 -t "[$initials]"
  fi
}
  4. add the gitmob_members prompt segment to the POWERLEVEL9K_LEFT_PROMPT_ELEMENTS or POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS arrays: 
    # The list of segments shown on the left. Fill it with the most important segments.
typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(
  # os_icon               # os identifier
  dir                     # current directory
  vcs                     # git status
  gitmob_members          # git-mob members
  prompt_char             # prompt symbol
)
  5. reload Powerlevel10K: 
    . $POWERLEVEL9K_CONFIG_FILE

Bash

Add the initials to PS1, in ~/.bashrc:

function git_initials {
  local initials=$(git mob-print --initials)
  if [[ -n "${initials}" ]]; then
    echo " [${initials}]"
  fi
}

export PS1="\$(pwd)\$(git_initials) -> "

Fish

Add the following functions to .config/fish/config.fish:

function git_initials --description 'Print the initials for who I am currently pairing with'
  set -lx initials (git mob-print --initials)
  if test -n "$initials"
    printf ' [%s]' $initials
  end
end

function fish_prompt
  printf "%s%s ->" (pwd) (git_initials)
end

Uninstall

  • git-mob ships with an uninstall sub-command which cleans up and removes the top-level mob plugins and deletes itself:

    git mob uninstall

Usage

  • TODO; coming as the project nears v1.0

Sub-command help

git-mob contains help for the various sub-commands:

git mob -h

⚠️ When requesting help make sure to use the short -h flag as git may intercept the full --help flag

$ git mob -h
A git plugin to help manage git coauthors.

Examples:
   $ git mob jd                                      # Set John as co-authors
   $ git solo                                        # Return to working by yourself (i.e. unset all co-authors)
   $ git mob -l                                      # Show a list of all co-authors, John Doe should be there

Usage:
  git mob [flags]
  git mob [command]

Use "git-mob [command] -h" for more information about a command.

Troubleshooting

If you run into trouble you can ask go-git-mob to write some diagnostics to a log file by setting the following environment variables:

Variable Default Description
GITMOB_LOG_LEVEL "fatal" "fatal", "error", "warning", "warn", "info", "debug"
GITMOB_LOG_FORMAT "text" "text" or "json"
GITMOB_LOG_FILE "" path to a log file; when empty logs go to STDOUT

Dial up log levels to show more detail:

GITMOB_LOG_LEVEL=debug git commit -m "my log message"

Capture log messages to a file:

GITMOB_LOG_FILE=./mob.log GITMOB_LOG_LEVEL=debug git commit -m "my log message"

Roadmap

See open issues and specifically the v1.0 - feature parity project board for a list of known issues and up-for-grabs tasks.

Contributing

See the CONTRIBUTING guide for local development setup and contribution guidelines.

License

Distributed under the GPU v3 License. See LICENSE for more information.

Contact

David Alpert - @davidalpert

Project Link: https://github.com/davidalpert/go-git-mob

Acknowledgements