jwu910 / check-it-out

A command line interface for Git Checkout. See branches available for checkout.

---

Check it out, before you checkout.

Check It Out lets you interactively see and choose what branch you want to check out without the hassle of trying to type out a long or confusing branch name. Checking out branches just got even simpler!

• Requirements
• Compatibility
• Installation
  • Installing from source
• Local development
• Usage
• Features
• Settings
• Contributing
• Contributors
  • Acknowledgements
  • License

Requirements

Node >= v16 - note: developed and tested on Node 16 and up. There isn't a guarantee this will work on earlier versions.

Git - Required for core features

Compatibility

Check It Out currently has known issues with Windows. Some users have reported it working while others have reported that it does not. It is built and tested mostly in an Arch Linux environment with some user testing on MacOS and other Linux distributions. We're currently looking for help figuring out why Check It Out is unstable on Windows. See CIO-128

Installation

We're on NPM!

npm install -g check-it-out

Installing from source

Fork or clone the repository

git clone https://github.com/jwu910/check-it-out.git

Navigate to your repository directory and run

npm install

Create a symbolic link to the entry point

In the repository directory run:

npm link

Local development

From your repository directory run

npm run build

To start the application you can run

node dist/index.js

or

npm start

If you want to test your local build in other repositories, you can use npm link which will let you run your local build files with the cio or checkit aliases.

Usage

To get started, just run:

checkit

or

cio

Features

See a git log for the highlighted ref by pressing SPACE

Commands	Description
j/k, ▼/▲	Navigate the list
h/l, ◄/►	Previous/Next remote
Ctrl+r	Refresh list with a fetch and prune
enter	Select highlighted item
y	Copy highlighted item
space	Git log
&	Filter lines - enter blank search to show all lines
/	Search Lines
n	Jump to next search result
N	Jump to previous search result
q, Ctrl+c, esc	Quit

Settings

Git log argument validation is planned, but not finished. Currently, if the git log fails, space should not crash the app, but the process should not spawn at all.

Configurable settings can be found at ~/.config/configstore/check-it-out.json

Options include:

• gitLogArguments
  • Type: Array
  • Default: ['--color=always', '--pretty=format:%C(yellow)%h %Creset%s%Cblue [%cn] %Cred%d ']
  • Array of strings of valid git log arguments.
• sort
  • Type: String
  • Default: -committerdate
  • Sort references by latest commit date. Value must be a valid sort key or Check It Out will break on start.
• themeColor
  • Type: String
  • Default: #FFA66D
  • A hex color code to style Check It Out

To reset Check It Out to its original configurations listed above, start with the flag --reset-config:

cio --reset-config

Contributing

Please refer to the Contributing Guidelines before contributing.

See the rest of our issues

Contributors

This project wouldn't have been possible with the help so many contributors both in and out of the source code. I look forward to working with you as this project continues to evolve and improve.

Brandon Benefield 📖	Aaron Casanova 💻	Drew Brokke 💻 🤔 🚧	Johanna Tchon 💻	Jenell Pizarro 📖	Rebecca Hong 🎨	Jesse Ma 💻
Kien Do 💬 🐛 🤔	Vu Tran 💬 📖 🤔 📢	Efrain 'Rain' Rivas 💬 🐛 💡 🚇 💻 📖	Phuc Le 💬 📢	Can Cellek 💻 📖	Aras Atasaygin 🎨	Donald Lika 💻
Connor Markwell 💻	ahlaw 💻	Kwadwo Busumtwi 📖	Dev Kant K Chouhan 📖	Jaya Krishna Namburu 💻	Céleste Robinson 📖	Juliardi عبدالله 💻
Omar Roa 📖	Rachana 💻	aksappy 🐛	Mahendra Kumar 💻 📖	Anthony Camarillo 💻 👀 🚧	TheCoolBlackCat 💻 📖	Jimmy Vu 📖
Catherine Njenga 📖	Himanshu Chauhan 🐛

Acknowledgements

@drewbrokke was the initial spark that inspired the creation of this project and encouraged me to let me curiosity drive this forward. @kiend gave me the inspiration and motivation to finish this project after letting it sit for so long. Check This Out. Thank you both for the encouragement and support through my career.

Logo Design by @arasatasaygin @openlogos

License

MIT @ Joshua Wu

check-it-out's Issues

Add column for remote path

Add a column that prints what the remote url resolves to.

Refactor: Refactor using react-blessed

https://github.com/Yomguithereal/react-blessed

It just makes sense...

Feature: Implement Tabs

Branches should be grouped by remotes and sorted into tabs.

h/l, left/right should switch between tabs

l currently selects, and should be unset first.

Tabs should be listed above headers and highlight current remote.

Documentation: Add contributing guidelines

Fetch on startup throws an error.

Introduced with refresh hotkey

Possibly change the structure of how the data is listed

Reconsider data structure to be more descriptive with branch names. If a user has multiple remotes with few branches, you can easily see three masters right next to each other.

Feature Request - Local only branches

Branch could indicate branches that are on a user's local repo, but NOT on any remote.

Request: Compatibility with Node 6

Node 7 is currently required due to the use of async await functions.

Looking to add Node 6 and compatibility and maybe older versions in the future as well.

If this project is required to build before deployment, we may have to move that route which would require some reorganization.

Implement testing suite

Need find and implement a testing suite to test utility functions.

I have used Jest for web app projects, but not for CLI tools.

Show help page on window

Should include a hotkey to show/hide help page.

? should toggle the help window.

Clean up index.js code

Code is messy and hard to read. Need to componentize code

---

check-it-out/index.js

Lines 22 to 27 in 28797e4

	* @todo Clean up index.js code
	* @body Code is messy and hard to read. Need to componentize code
	*/
	if (!process.argv.slice(2).length) {
	const screen = dialogue.screen();

---

This issue was generated by todo based on a @todo comment in 28797e4 when #74 was merged. cc @jwu910.

Handle current branch

Program should handle attempt to check out currently checked out branch

Branch does not change between detached heads

If current branch is a detached HEAD, attempting to change to another detached HEAD will not work.

Documentation - Update readme with License

Bug: If current working directory is not a git repository, app breaks

The app hangs in a blank state if the cwd is not a git repository.
Can simply check if the currentBranch() method returns a valid response or not.

Program should throw an error and print the correct error message for the user

git rev-parse --is-inside-work-tree will return true if path is inside a git repo. otherwise it will go to stderr

Windows Compatibility

Currently does not work with windows.

Some research has explained that this needs to be a portable node app. Reasons the node app probably does not work is the difference in file system paths and how '/' does not resolve on windows systems.

Use path.resolve() as a start.

Documentation - Install from source

Resize table on window resize

App window sizes should be responsive to terminal window size.

Build a keyMap utility

Add left and right functionality to change remote. Add getUniqueRemotes method here.

---

check-it-out/index.js

Lines 39 to 44 in dedef3a

	screen.render();
	};
	/**
	* @todo: Build a keyMap utility
	* @body: Add left and right functionality to change remote. Add getUniqueRemotes method here.

---

This issue was generated by todo based on a @todo comment in dedef3a when #79 was merged. cc @jwu910.

Formatting: Confirmation question does not accommodate smaller terminal windows

Fetch on user request, not automatically. Will not work when user has no internet access.

Bug: Promise error when creating a new local branch

When checking out a branch that exists on a remote, but not user's local, the following error occurs:

[LOG] fatal: Unable to create '/home/joshua/programming/check-it-out/.git/index.lock': File exists.

Suspecting that Git is trying to execute another command before the first command has completed. This would most likely be an incorrect use of Promises with the async and await keywords in the Git utilities.

Improper use of .then()

Using await someAsyncFunction().then(//do something)

Should we be using try catch here and then continuing?

Add scrollbar indicator

Consider executing git fetch before populating branch list

Setup build dependencies

Find a quicker way to load branches on app start.

Can probably skip the fetch on start up to help save startup time. Maybe revert the auto-fetch so it just fetches on "refresh".

Change indicator for current branch to a column on the selection list

Remove "Path" column

Path column could provide different data. Seems unnecessary to list ref path now...

Maybe list last commit?

Fixed width cuts of 2nd column if user has a very long branch name

Change

{
width: '70%'
// to
width: 'shrink'
}

Document utils functions

Clean up and organize elements

Blessed element creation is messy and hard to read.

Update status bar and help

Should hotkey help information always be shown?
Add current remote tracker/tabs

Infrastructure: Reorganize blessed objects

Need to compartmentalize blessed screen and window objects.

Currently, code is confusing to read. Entry point should be very minimal, only instantiating the main screen.

Add update notifier to package

https://github.com/yeoman/update-notifier

Migrate components

Move objects into components:
Screen
Table
Questions
Status bar
etc.?

Need to set up a github.io page

We should set up a github pages hosted site to give some more visual flair to the readme.

Feature: Stash on change

If user has unstaged changes, app should prompt user to stash changes prior to checking out.

"Remote" heading doesn't handle branches that are grouped

Branches that are grouped inside of a remote get mis-labeled as having their group be the remote
e.g

remote: origin
branch: hotfix/fix-print-out

since hotfix is a grouping, it would show up as origin/hotfix/fix-print-out; therefore all "hotfix" branches get marked as having hotfix for a remote

I'm guessing these lines (or close to it) are the culprits

check-it-out/index.js

Lines 53 to 55 in 0b3a1b1

	const branchInfo = val.content.split(/\s*\s/).map(column => {
	return column === 'local' ? '' : column;
	});

Feature: Spacebar to git log selected branch

Add jack-cli as a dependency and invoke jack on spacebar.

This would give user ability to quickly view a log as well as quickly check commits

If user has no internet, unhandled exception is thrown and branch list is not generated.

Possibly generate a local text file storing output of git for-each-ref
Need to access local git information w/o fetching
Need to brainstorm.

When a user attempts to use check-it-out while not connected to the internet, the utility command to build the branch lists will not work. A possible solution has not been found yet.

Handle unstaged changes

Program should prompt user about unstaged changes and provide options

Formatting: Module exports can be reduced to one value

check-it-out/utils/git.js

Lines 116 to 121 in 0b3a1b1

	module.exports = {
	buildListArray: buildListArray,
	checkoutBranch: checkoutBranch,
	createBranch: createBranch,
	currentBranch: currentBranch,
	fetchBranches: fetchBranches,

{
  function: function
}

// can be

{
  function
}

Switch column names so longer names are on the right.

Fix Typos

Need to fix typos in the readme and contributing guidelines.

First time checkout

If branch is not on local, but exists on origin, git checkout should be called without the remote param.

e.g.: git checkout test-branch instead of git checkout origin/test-branch

Sort branches by most recently checked out

This is especially helpful when there are tons of branches and you don't want to have to scroll through the whole list to find the ones that you most commonly use

Update descriptions

Descriptions and readme should be more descriptive.

Warning dialogue displays on load

OS: Arch Linux
Term: Gnome Terminal

Warning window briefly displays "Terminfo parse error"

Redesign structure. Check It Out should cover the entire screen

Known issue: if the use of the list-table covers the entire terminal window, wider terminal windows will create unwanted space between columns (Haven't figured out a solution to this yet)

• Status bar should stretch across the entire terminal window