kowainik/hit-on

:octocat: Kowainik Git Workflow Helper Tool

Hit On

Kowainik Git Workflow Helper Tool.

You can find the description of the workflow here:

• Kowainik Git Workflow

hit-on provides the hit binary with a convenient command-line interface to improve the interaction with git in a compatible way with the described working methods. It saves time for people who use this workflow on a daily basis, helps beginners expand their insight of the core VCS processes and makes collaboration between team members easier during development.

Here is an example of how you can see the list of issues and the issue description with hit:

Or how you can see pretty short stats about your changes:

Getting started

Prerequisites

To start using hit make sure that you have the following tools installed on your machine:

• git — hit is a wrapper around git

• hub – to make PRs to GitHub directly.

• Optional: diff-highlight — for pretty output of the hit diff command
  • Linux installation instructions

    cd /usr/share/doc/git/contrib/diff-highlight/
    sudo make
    sudo chmod +x diff-highlight
    sudo ln -s diff-highlight /usr/local/bin/diff-highlight

  • macOS installation instructions

Installation

There are several methods to install the hit tool. You can choose the one that you are most comfortable with.

Download from releases

You can download the hit binary directly from the GitHub releases:

• hit releases

After downloading, make it executable and copy it to a convenient location, for example:

chmod +x hit-linux
mv hit-linux ~/.local/bin/hit

Build from source

NOTE: the project is written in Haskell, so you need to have one of the Haskell build tools installed. See this blog post for installation and usage instructions.

You need to follow these steps:

1. Clone the repository from GitHub

   git clone https://github.com/kowainik/hit-on.git

2. Step into the directory

   cd hit-on

3. Install the project with one of the build tools

• Cabal

     cabal new-install hit-on

  Note: make sure you have ~/.cabal/bin in your $PATH
• Stack

     stack install hit-on

4. Make sure that hit is installed:

   hit --version

macOS package manager

Currently, this method of installation is not supported. See this issue for more details or if you want to help.

Ubuntu package manager

Currently, this method of installation is not supported. See this issue for more details or if you want to help.

Setting up

Follow the steps below to configure hit :

1. Enable autocompletion by calling the following command:

   source <(hit --bash-completion-script `which hit`)

   Add it your personal config file (like ~/.bashrc) to enable automatically.
2. Specify your GitHub login in the global .gitconfig

git config --global user.login <your_login>

3. This step is only required if you want to use hit with private repositories.

   1. Create OAuth token on GitHub. The following scopes for the token should be specified:

   2. Copy the generated token.

   3. Export token as an environment variable

      export GITHUB_TOKEN=<paste_generated_token_here>

Commands

Command	Description
hop	Switch to branch and sync it
fresh	Rebase current branch on remote one
new	Create new branch from the current one
stash	Stash all local changes
unstash	Unstash previously stashed changes
commit	Commit all local changes and prepend issue number
uncommit	Reset to the previous commit saving the changes
fix	Fix requested changes to the last commit
amend	Amend changes to the last commit and force push
issue	Show the information about the issue
push	Push the current branch
sync	Sync local branch with its remote
resolve	Switch to the main branch, sync and delete the branch
clear	Remove all local changes permanently
current	Show info about current branch and issue (if applicable)
status	Show current branch and beautiful stats with COMMIT_HASH (by default HEAD)
diff	Display beautiful diff with COMMIT_HASH (by default HEAD)
clone	Clone the repo. Use 'reponame' or 'username/reponame' formats
log	Outputs the log of the current commit or COMMIT_HASH
tag	Create or delete the specified tag TAG_NAME

Usage

The best way to demonstrate the power of the hit tool on a day-to-day basis with our workflow is to go through the entire workflow step by step, solving an ordinary problem of the typical git user.

Here we assume that you work with origin remote.

hit clone

If you don't have the repository locally, you need to clone it. With the git tool you would need to specify the full URL which you can get from the repository GitHub page.

git clone [email protected]:username/project-name.git

hit can simplify this process a bit. If you want to clone the project which is under your GitHub username you can write:

hit clone my-project

If this is not your personal repository then you can use clone command in the following way:

hit clone owner-name/project-name

hit hop

When you want to start working on a new issue, you usually want to make sure you're using the latest version of your project. As a git user you may use the following commands:

git checkout main
git pull --rebase --prune

With hit you can just:

hit hop

hit issue

Now you need to decide which issue you want to work on. You can use the hit issue command to see the full list of all open issues. After choosing the number of the issue, let's say 42, call hit issue 42 to see the details of that issue.

hit new

Start your work in a new branch. According to our workflow, branch names should have the following form:

<user_login>/<issue_number>-<short_issue_description>

With git you can create a branch using the following command:

git checkout -b my-login/42-short-desc

hit allows you to accomplish this task in an easier manner:

hit new 42

It uses the issue title to generate a short description.

hit status

Before commiting your changes, you may want to inspect short stats about your work. With git you usually call the following command:

git status

However, the same hit command produces better output:

hit status

hit diff

If you want to see detailed diff of your changes, use hit diff command. If you have diff-hightlight installed then hit diff outputs much nicer diffs.

hit commit

After finishing your work on that issue, you need to commit your changes. With git you would do the following:

git add .
git commit -m "[#42] Implement my feature

Resolves #42"

With hit you need only to specify the text of the commit to get the same result:

hit commit "Implement my feature"

or even simplier:

hit commit

And the commit name would be the title of the corresponding issue at GitHub (if you are currently in the branch named as described above).

Note that you don't need to keep in mind the current issue number. However, if you want to refresh the context about the issue, use the hit current command.

hit push

After committing your changes locally, you need to push them to the remote repository. It's usually a good practice to push only the current branch.

The git command for this is a little bit verbose:

git push -u origin my-login/42-short-desc

hit allows you to save several keystrokes:

hit push

Note: hit push command can be combined with the hit commit command using -p|push flag in the latter command.

hit commit --push

hit sync

After opening the pull request, some of the reviewers suggested changes that you applied as commits to the remote branch via GitHub interface. Now you need to sync your local branch with the remote one.

With git you can do the following:

git pull --rebase origin my-login/42-short-desc

However, with hit you can just:

hit sync

hit fresh

While you were waiting for the second round of reviews, another pull request was merged to the main branch. Now you need to apply the new main changes to your local branch.

With git you can do the following:

git fetch origin main
git rebase origin/main

Again, with hit you can do better:

hit fresh

hit fix

Now you need to make changes to your work locally according to the code review and push them to the remote repository.

git requires from you to do several steps to accomplish this simple task:

git add .
git commit -m "Fix after review"
git push origin my-login/42-short-desc

hit helps you with this as well:

hit fix

hit amend

Oops, you've just realised that you have made a typo in your work! So you fixed the typo. But now you want to update the remote branch without creating a new unnecessary commit.

With git you can do the following:

git commit -a --amend --no-edit
git push origin my-login/42-short-desc --force

With hit you can simply:

hit amend

hit resolve

Hooray, your PR just got merged! It's time to clean your local repository and start working on a new issue!

With git you would do the following:

git checkout main
git pull --rebase --prune
git branch -D my-login/42-short-desc

With hit you can finish your work faster:

hit resolve

hit log

Hooray, your PR just got merged! It's time to clean your local repository and start working on a new issue!

With git you would do the following:

git log --oneline --decorate [COMMIT_HASH]

With hit you can finish your work faster:

hit log [COMMIT_HASH]

Troubleshooting

If you see

$ hit hop
fatal: ambiguous argument 'origin/HEAD': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
hit: readCreateProcess: git "rev-parse" "--abbrev-ref" "origin/HEAD" (exit 128): failed
  origin/master
...skipping...

then you can run

$ git remote set-head origin -a

to synchronise with the remote, fetch and set origin/HEAD locally.

Acknowledgement

Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY.

hit-on's Issues

`hit new` fails if the branch already exists

A good behaviour might be to catch this error, and just switch the command to a hit hop instead

Add `Resolves #ISSUE_NUMBER` to the body of commit message

Could be an optional flag or something else.

Implement `hit status` command with nice output

See example of the output here:

• https://stackoverflow.com/a/55202319/2900502

Add `--force` flag to `push` command

Well, sometimes this is really needed...

Smart branch name detection

With the given issue number it should look like: username/XXX-issue-title

If there is no issue the branch should not be created.

Add `issue` option to `hit new` command

Sometimes when you work on something, you don't have an issue for that. But you realize it only after you did all work. It would be really convenient to have a command that allows you to create issue from your terminal. Something like:

hit new-issue "Implement urgent fix for the image processing"

This command should create issue on GitHub and output the number of created issue to your terminal which you can use later with hit new command.

P.S. Probably better name than new-issue should be used.

parseOwnerRepo expects a .git suffix but that is optional

Implement command like "finish" to switch to master and delete current branch

hit log

Some command that shows log in pretty format. Better than default git log 🙂

Remember: git reflog

Improve rendering of `hit issue <n>` command

Configure `hit` installation for the Ubuntu

Implement command to create new branch: `hit new`

Bump up to GHC 8.6.5

hit stash / unstash

• Stash:

  git add .
  git stash

• Unstash

  git stash pop

Implement unit tests for `parseOwnerRepo` function

This function:

hit-on/src/Hit/Issue.hs

Line 98 in 4f8d392

parseOwnerRepo :: Text -> Maybe (Name Owner, Name Repo)

It would be nice to have several tests with the hspec library.

Make `issue` work with private repos

Implement basic CLI interface

--help option will be enough for the start

Configure GitHub releases on Travis CI for OSX

Implement command to sync with current branch: `hit sync`

Write documentation

README with usage examples for every command

[RFC] Support workflow with forks

hit is very convenient when working with repos you own. But sometimes I still need to work with forks. I wonder, whether it's possible to make hit work with forks without sacrificing current UI.

My typical workflow with forks include:

1. Fork repo on GitHub.
2. Clone my fork (already can be achieved by hit clone command).
3. Do my work (all hit command work here)
4. Show all remotes (can be hit remotes command)
5. Add remote of the original repo (can be hit add-remote <owner>/<repo>)
6. Rebase on the branch from the remote repo (probably can patch hit fresh command so it understands hit fresh <remote>/<repo>).
7. Push and open PR.

What do you think?

Implement `hit diff` command with pretty diff

This command will show pretty diff output like in the image below:

The command to do this:

git diff HEAD~1 --color=always | diff-highlight | less -rFX

However, diff-highlight requires installation. Instructions:

1. Ubuntu: https://qiita.com/SakaiYuki/items/2814d417d0bec59046bb
2. Macos: https://www.viget.com/articles/dress-up-your-git-diffs-with-word-level-highlights/

This to look for:

1. Check whether diff-highlight is on path and call ordinary diff

Think on ways to test `GitHub-related functionality automatically

This issue was partially discussed under PR: #59

Add --force to `hit fix`

Don't hardcode `kowainik` and `hit-on`

😂

Add --me option for issue command

This should give the list of the issues where the current user is the assignee

Describe the required oauth privilages needed

When generating the personal access token, we need to specify the scope needed for the token. This should be specified in the README

Align `hit status` output better

I noticed that numbers in the output of hit status are not aligned properly. So one minor tweak is required for this command.

Configure `hit` installation with `brew`

Make `new` command take branch names

Sometimes when I create a new branch, it's not attached to some issue. For example, I want to fix docs, but I don't want to create an issue for that. Because hit works with issue numbers, it's not possible to create branches not under some issue.

I propose to make hit new command a little bit smarter. It will parse argument, and if it's a number then it should keep current behavior. But if it's arbitrary text, it will create branch from this text prefixing with user name.

$ hit new fix-docs
> git checkout -b chshersh/fix-docs

`hit clear` command

It should clear all modified/new/deleted files and return to the previous state.

Configure download from releases

Implement `hit cur` command

Like hit current but shows only branch name.

Should we align issues?

I noticed that issues are not aligned when there are different sizes of issue numbers. Aligning is more complicated, and it's not that important. I just wonder, whether we should align them or not 🙂

P.S. Extra space after arrow is because of my recent changes... I will work on that to prettyfy.
P.P.S. We do a lot of pretty-printing of tables with alignment here, I wish there was a library to do this easily...

Add "fix-push" command: `hit fix`

This should ammend changes and force-push the branch

Add issue number prefix to the commit names: `hit commit`

Like this: "[#XXX] Here goes what user wrote"

Add `hit uncommit` command

to roll back to the previous commit but saving the changes of the latest commit itself

Find out the way to get info about the issue

Set up autocompetion

Patch `hit status` to tell about rebase in progress

hit current to show current branch

And maybe and issue info?

When new branch for issue created add the user as assignee

Blocked by #108

If there are rights for that.

Implement command to push current branch: `hit push`

With --set-upstream option given

Show conflict files during rebase in `hit status`

Add hit clone command

It should be simpler than git clone to use. I have several options about how to structure this, but here is the one I personally like:

hit clone project-name

^ this clones username/project-name repo using ssh

But

hit clone org-name/project-name

^ should clone the specified repo and specified GitHub user/org name.

Maybe there are any other ideas, what do you think?

Implement "git-new"-like command: `hit hop`

Migrate to `shellmet`

It's on Hackage 😏

http://hackage.haskell.org/package/shellmet

Implement option or command to commit without issue prefix

`hit fix` - make commit and push

At the moment we have hit fix command which amends the changes to the latest commit and force pushes the branch. I guess the better name for this command is hit amend.

I can see the better usage for the hit fix command: to make the separate commit (without the issue prefix) and to push the branch.

So, to resolve this issue ones need:

• Rename hit fix to hit amend
• Implement hit fix command which will take the optional string as the commit message (if the optional string is not provided then use "Fix after review" message), make the commit to the current branch and push the current branch.

Implement "git-sync"-like command: `hit fresh`