lucaslarson/gunstage

🔫  `git unstage` as a service: a Git plugin for the shell that automagically remembers all the different commands there are to remove files from staging and when to use each

gunstage

🔫 git unstage as a service

What

There are at least nine ways to unstage files in a Git repository. Remembering which versions of Git support which syntax, under which circumstances, reduced my productivity enough to publish this software in response.

This is a command-line shell plugin for undoing git add. Too many staged files? Can’t remember if it’s git reset HEAD or git restore --staged --? Just remember gunstage or git unstage.

gunstage works exactly as you would expect it to as it performs the opposite of git add. You can unstage directories and specific files in as few commands as you’d like: gunstage file1.txt file2.txt directory/.

Want to unstage everything? Well that’s as easy as gunstage --all or gunstage -A.

Why

There is no git unstage command packaged as part of Git’s default tooling. While git restore --staged often performs the task, it’s not an obvious formula based on Git’s other commands. git restore --staged is also unreliable, having entered Git’s vocabulary in 2019, after some 14 years of releases without it. Many older releases remain in the wild and git restore causes them to fail and choke. This software gracefully and silently accounts for those situations by always sending the syntax that Git used from 2005 until 2019: git reset.

Instead of keeping up with the latest incarnation of Git, whose manual says git restore “IS EXPERIMENTAL” and “THE BEHAVIOR MAY CHANGE” (emphasis in original), you can let this script do the remembering for you.

Minutiæ of the pedantic and querulous variety

To unstage content in a Git repository – that is, to undo a git add – you must remember which commands are still in use out of the many I’m aware of having been recommended so far:

1. git restore --staged (source),

2. git reset HEAD (source),

3. git reset -q HEAD -- (source (via))

4. git reset (source),

5. git restore --staged -- (source),

6. git reset HEAD -- (source),

7. git rm --cached (source),

8. git reset -- (source), and even

9. git rm --cached -- # ffs (source).

Next, you must be aware of repository context: if the repository is new and no commit has occurred yet, then git restore --staged won’t work, but gunstage will.

Enter

gunstage # 🔫 git unstage as a service
git unstage # 🔫 it just works!

Its name is an abbreviation and portmanteau of git unstage arising by analog from Oh My Zsh’s other Git aliases.

How

The scripts are written in Bourne shell-flavored, KornShell- and Zsh-compatible Bash, which is masquerading as Z shell with a .zsh filename extension so Oh My Zsh recognizes it as a plugin. What does that mean? The syntax is as low-tech as possible while performing sophisticated work to do one thing and do it well: git unstage.

Installation

gunstage can be installed as a plugin, installed using Fig, or you can just clone this repository, run the following command, and then restart your terminal:

$ printf '%s\n' '. /path/to/gunstage.plugin.zsh' \
  >>"${HOME%/}"'/.'"${SHELL##*[-./]}"'rc'

Requirements

• Zsh 5.8 (or Ksh 93 (or Bash 5.0)), and

• Git 2.17.

Testing

I tested gunstage atop Zsh 5.8 and Bash 3.2 using Git:

• 2.17 on Ubuntu 18.04,

• 2.20 on Debian 9.12,

• 2.28, 2.29, and 2.30 on macOS 11.0 and Alpine 3.11 and 3.12, and

From macOS, I use iTerm2; from iOS, I use iSH.

Credit

This repository’s preview image was created by Twitter in 2018.

gunstage's Issues

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.

add a `Mentioned in Awesome` button

add the “Mentioned in Awesome” button as seen at marwanhawari/stew@2f6a9dd § stew:

---

live:

[![Mentioned in Awesome](https://github.com/sindresorhus/awesome/raw/a90737eb91368b3be912d1759f9573203ef9e70d/media/mentioned-badge.svg)](/unixorn/awesome-zsh-plugins)

---

or archivable / for posterity:

[![Mentioned in Awesome](https://web.archive.org/web/20220305135317id_/github.com/sindresorhus/awesome/raw/a90737eb91368b3be912d1759f9573203ef9e70d/media/mentioned-badge.svg)](https://web.archive.org/web/20220305180324/https://github.com/unixorn/awesome-zsh-plugins/commit/b47bbcdea53c8bc65ca28641b7751977eba500a8)

remove double quotation marks where not suggested by ShellCheck

ShellCheck doesn’t care about quoting variable assignments like this one:

gunstage/bin/git-unstage

Line 20 in 9d7673a

IFS="$(printf '\n\t')"

Even when ShellCheck’s --enable is set to all and no matter if --severity is set to style, let alone error, removing the double quotes and running the following has a return value of 0 – c.‑à‑d., which is to say – no warnings or errors:

"$(command -v shellcheck)" \
  --enable=all \
  --severity=style \
  --exclude="" \
  --shell=sh \
  -- ./bin/git-unstage

---

An unsurprising warning would be:

In ./bin/git-unstage line 20:
IFS=$(printf '\n\t')
    ^--------------^ SC2248: Prefer double quoting even when variables don’t contain special characters.

Did you mean:
IFS="$(printf '\n\t')"

there’s no attribution for the social media preview image

Use of Twitter’s Twemoji requires attribution¹ which is not present,² but is in use.³

---

Footnotes

1. https://github.com/twitter/twemoji/tree/a5b334b2b7#attribution-requirements ↩

2. https://web.archive.org/web/20220120165659/github.com/LucasLarson/gunstage/search?q=Twemoji ↩

3. https://web.archive.org/web/20220120220252/socialsharepreview.com/?url=https%3A%2F%2Fgithub.com%2FLucasLarson%2Fgunstage ↩

Markdown syntax errors

The Markdown syntax in these files isn’t to specification.

• https://github.com/LucasLarson/gunstage/blob/abfd1120a6e47ec5c902d31c5710cfc4d381083d/.github/ISSUE_TEMPLATE/bug_report.md
• https://github.com/LucasLarson/gunstage/blob/0a75bb931aea19e8fe91ccd7e72eeb6de2c9dd97/.github/code_of_conduct.md

`actions/setup-ruby` is deprecated

gunstage/.github/workflows/changelog.yml

Line 17 in d170bd6

uses: actions/[email protected]

actions/setup-ruby is deprecated;¹ ruby/setup-ruby² is the recommended replacement.

---

1. actions/setup-ruby@e932e7a#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R9
2. https://github.com/ruby/setup-ruby

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

github-actions

.github/workflows/changelog.yml

• actions/checkout v4
• ruby/setup-ruby v1
• ad-m/github-push-action v0.8.0

.github/workflows/super-linter.yml

• actions/checkout v4
• github/super-linter v5

---

• Check this box to trigger a request for Renovate to run again on this repository

remove array if possible

we might be able to remove the files array:

gunstage/bin/git-unstage

Lines 29 to 31 in 4d58de8

	files=(
	"${@:-.}"
	)

and replace the for loop’s files iterator:

gunstage/bin/git-unstage

Line 35 in 4d58de8

for file in "${files[@]}"; do

with an ${if:-else} substitution like this:

for file in "${@:-.}"; do

---

If the array is gone, then both scripts will be POSIX-compliant and we’ll change these

gunstage/bin/git-unstage

Line 1 in 4d58de8

#!/usr/bin/env bash

gunstage/gunstage.plugin.zsh

Line 1 in 4d58de8

#!/usr/bin/env bash

to this

#!/usr/bin/env sh

installation instructions

A plugin needs plugin-installation instructions.

Consider linking to olets/zsh-abbr’s plugin-agnostic instructions.

the changelog fails Super-Linter’s `markdownlint`

github-changelog-generator inserts overabundant vertical space,¹ about which GitHub Super‑Linter’s instance of markdownlint complains.

Footnotes

1. https://github.com/LucasLarson/gunstage/blob/a420181539d38ea873f489f24176047c19aee48d/changelog.md#L170-L174 ↩

calling `gunstage` from outside a repository returns a success exit code

Calling gunstage currently shows a help message when called from outside a git repository. It should also return a failing exit code; git itself returns 128 in such situations.

Please add a top-level license file

Describe the bug

The license is only in the gunstage script, so it doesn't get automatically found and displayed by github on the main repository page

To Reproduce
Steps to reproduce the behavior:

N/A

Expected behavior
If there's a separate LICENSE file, github will parse it and display your license in the main page of the repository

Desktop (please complete the following information):

• Browser: All

Twitter

add year that Twitter created the repo’s preview image

broken link

gunstage/bin/git-unstage

Line 30 in 0b340ec

# https://github.com/gggritso/gggritso.com/commit/a07b620

it’s now https://github.com/gggritso/site/commit/a07b620

---

extraordinarily, the link in the readme, to the same repository, still works (likely because it’s using the unabbreviated commit hash)

gunstage/readme.adoc

Line 47 in 86c4769

1. `git reset -q HEAD --` (https://github.com/gggritso/gggritso.com/blob/a07b620/_posts/2015-08-23-human-git-aliases.md#L45[source^] (https://news.ycombinator.com/item?id=17987033#17987696[via^]))

`git.io` deprecation

@github ends 11 years of serving git.io redirections on 2022-04-29¹ after providing 3 days warning. This repository appears to contain affected content: search: git.io

Footnotes

1. github.blog/changelog/2022-04-25-git-io-deprecation ↩

add support for `git unstage --all`

add the ability to unstage all changed staged files in a Git repository; the current implementation unstages files only the current working directory and below

gunstage/bin/git-unstage

Lines 26 to 28 in 4d6e288

	# run the same command against each argument, if any
	# otherwise use `.` for everything in the current directory and below
	for file in "${@:-.}"; do

another `git unstage` syntax found in the wild

git reset -q HEAD -- (source (via)) belongs in this list:

gunstage/readme.adoc

Lines 45 to 52 in a011d0e

	1. `git restore --staged` (https://stackoverflow.com/a/16044987[source^]),
	1. `git reset HEAD` (https://stackoverflow.com/a/6790291[source^]),
	1. `git reset` (https://stackoverflow.com/a/6790285[source^]),
	1. `git restore --staged --` (https://github.com/iain/dotfiles/commit/4c8f8cf7b849d723cbd0e029457dd24c42ea6263[source^]),
	1. `git reset HEAD --` (https://stackoverflow.com/a/5798967[source^]),
	1. `git rm --cached` (https://stackoverflow.com/a/5798967[source^]),
	1. `git reset --` (https://stackoverflow.com/a/6919257[source^]), and even
	1. `git rm --cached -- # ffs` (https://stackoverflow.com/a/30231316[source^]).

---

It’ll require manually updating:

gunstage/readme.adoc

Line 13 in a011d0e

There are at least eight ways to unstage files in a Git repository.

regression: filenames with spaces cause unexpected results on Linux

Bug initially identified in #32 (comment):

filenames with spaces in them no longer mirror vanilla Git’s behavior. The wrong files are now unstaged if you perform the following sequence:

git init && touch a a\ b b # create three files: “a”, “a b”, and “b”
git add . # stage the new files
git unstage a\ b # try to unstage only “a b”, but “a b” is the only file that remains staged

After @unixorn’s 28d982b, the bug is no longer present on macOS 11.0.1, but is still present on:

• Alpine 3.12
• Ubuntu 18.04
• Debian 9.12

GitHub won’t recognize an Asciidoc code of conduct

in re #111 and 146394b24b:

When a @github repository has a code of conduct file at /.github/code_of_conduct.md, all goes according to plan. When, however, an equivalent Asciidoc code of conduct is saved to /.github/code_of_conduct.adoc, GitHub won’t see it.

What does that mean? There is a link to the repository’s “Code of conduct” at the bottom of the new “New issue” page, but only if the code of conduct is saved as a Markdown file with a Markdown‑like filename extension. No Asciidoc codes of conduct for now.

add fig installation instructions

gunstage is available on fig (archive) but that’s not mentioned in the readme.

related: #110, #122

∃ ≥ 5 ways to `git unstage`: `git reset --` seen in the wild

add it to the readme

b7f6919#r42893428

add mechanism to return current version number

gunstage --version

should return something like

gunstage/citation.cff

Line 13 in 4aae64a

version: 1.8.2

or alternatively, something like what git describe returns on a clone of this repository

v1.8.2-22-gae1db6d973

clear variables with `unset` instead of a subshell

instead of

(
  a=b
)

use instead

a=b
unset a

gunstage/bin/git-unstage

Lines 21 to 57 in a420181

	(
	# check whether we’re in a Git repository
	# https://stackoverflow.com/a/53809163
	if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
	# run the same command against each argument, if any
	# otherwise use `.` for everything in the current directory and below
	for file in "${@:-.}"; do
	# https://github.com/gggritso/gggritso.com/commit/a07b620
	git reset --quiet HEAD -- "${file}"
	# perform a `git status` only if the loop was successful
	done && git status
	else
	# we’re not in a Git repository
	# store the failed if as a return status
	# https://github.com/ohmyzsh/ohmyzsh/pull/9238#discussion_r484806772
	gunstage=$?
	# if called from outside a Git repository, then
	# provide instructions on how to use it
	printf 'gunstage must be called from within a Git repository\n'
	printf 'create a file and a repository, then stage and gunstage:\n
	touch file && # create a file called '
	printf '\xe2\x80\x9cfile\xe2\x80\x9d \x5c
	git init && # make a Git repository if necessary \x5c
	git add file && git status # stage the file you just created
	# now use \x60gunstage\x60 to unstage the file
	gunstage file # huzzah.\n\n
	gunstage # \xf0\x9f\x94\xab \x60git unstage\x60 as a service
	https://github.com/LucasLarson/gunstage\n\n'
	return "${gunstage}"
	fi
	)

commands not prepended by `command` can produce unexpected behavior

https://opengroup.org/onlinepubs/9699919799/utilities/command.html#tag_20_22_16

`git restore` requires `git --version` ≥ 2.23.0 or later

gunstage/gunstage.plugin.zsh

Line 29 in ecffcba

unstage="$unstage; git restore --staged --progress"

git restore is not available before Git 2.23.0

`grep --quiet` doesn’t port to BusyBox

gunstage/gunstage.plugin.zsh

Line 30 in 245c3fc

if (printf 'minimum version 2.23.0\n'; git --version) | sort --version-sort --key=3 | tail -n -1 | grep --quiet git; then

grep --quiet should be
grep -q which is portable but opaque

add support for `NO_COLOR` environment variable

Where git unstage will return a git status, there is no way to prevent color output:

• gunstage/bin/git-unstage

  Line 31 in f172b48

  command git status

• gunstage/bin/git-unstage

  Line 43 in f172b48

  done && command git status

This repository should adopt the closest existing standard – no-color.org’s¹ NO_COLOR environmental variable – to prevent color output on demand until git(1) itself supports it.²

Footnotes

1. jcs/no_color generates no-color.org ↩

2. As of November 2023, Git’s only test for $NO_COLOR is in t/chainlint.pl, where it was added in September 2022 (git/git@7c04aa7390) ↩

add DeepSource flair

add DeepSource’s no-open-issues badge (current;¹ erstwhile)² to the readme

Footnotes

1. ↩

2. ↩