Merge pull request #151 from blairconrad/update-docs

Update docs

Author: tummychow

.github/workflows/release.yml

@@ -1,14 +1,16 @@
 # The way this works is the following:
 #
-# The create-release job runs purely to initialize the GitHub release itself
-# and to output upload_url for the following job.
+# The create-release job runs purely to initialize the GitHub release itself.
 #
-# The build-release job runs only once create-release is finished. It gets the
-# release upload URL from create-release job outputs, then builds the release
-# executables for each supported platform and attaches them as release assets
-# to the previously created release.
+# The build-man-page job runs once create-release is finished.
+# It builds the man page and attaches it as a release asset to the previously
+# created release.
 #
-# The key here is that we create the release only once.
+# The build-release job runs only once build-man-page is finished. It downloads
+# the man page, then builds the release executables for each supported platform
+# and attaches them to the previously created release.
+#
+# The key here is that we create the release and man page only once.
 #
 # Reference:
 # https://eugene-babichenko.github.io/blog/2020/05/09/github-actions-cross-platform-auto-releases/
@@ -43,14 +45,12 @@ jobs:
           echo "GA_VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
           echo "version is: ${{ env.GA_VERSION }}"
       - name: Create GitHub release
-        # Todo: Maybe replace it with https://github.com/softprops/action-gh-release to generate a nice changelog?
+        # Todo: Generate a nice changelog using https://github.com/softprops/action-gh-release
         id: release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: softprops/action-gh-release@v2
         with:
+          name: ${{ env.GA_VERSION }}
           tag_name: ${{ env.GA_VERSION }}
-          release_name: ${{ env.GA_VERSION }}
 
   build-man-page:
     name: build-man-page
@@ -73,14 +73,10 @@ jobs:
           path: Documentation/git-absorb.1
           name: git-absorb.1
       - name: Attach man page to release
-        uses: actions/upload-release-asset@v1.0.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: softprops/action-gh-release@v2
         with:
-          upload_url: ${{ needs.create-release.outputs.upload_url }}
-          asset_path: Documentation/git-absorb.1
-          asset_name: git-absorb.1
-          asset_content_type: application/octet-stream
+          name: ${{ needs.create-release.outputs.GA_VERSION }}
+          files: Documentation/git-absorb.1
 
   build-release:
     name: build-release
@@ -166,7 +162,7 @@ jobs:
           mkdir -p "$staging"/doc
 
           cp {README.md,LICENSE.md} "$staging/"
-          cp Documentation/{git-absorb.1,git-absorb.txt} "$staging/doc/"
+          cp Documentation/{git-absorb.1,git-absorb.adoc} "$staging/doc/"
 
           if [[ "${{ matrix.target }}" =~ .*windows.* ]]; then
             cp "target/${{ matrix.target }}/release/git-absorb.exe" "$staging/"
@@ -179,11 +175,7 @@ jobs:
           fi
 
       - name: Upload release archive
-        uses: actions/upload-release-asset@v1.0.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: softprops/action-gh-release@v2
         with:
-          upload_url: ${{ needs.create-release.outputs.upload_url }}
-          asset_path: ${{ env.ASSET }}
-          asset_name: ${{ env.ASSET }}
-          asset_content_type: application/octet-stream
+          name: ${{ needs.create-release.outputs.GA_VERSION }}
+          files: ${{ env.ASSET }}

Documentation/Makefile

@@ -1,9 +1,9 @@
 build-manpage: git-absorb.1
 
-git-absorb.1: git-absorb.txt
+git-absorb.1: git-absorb.adoc
 	$(if $(shell which a2x),,$(error "No a2x in PATH; install asciidoc."))
 	$(info Building manpage. This may take a few moments...)
-	a2x -L -d manpage -f manpage git-absorb.txt --attribute man-version=${GA_VERSION}
+	a2x -L -d manpage -f manpage git-absorb.adoc --attribute man-version=${GA_VERSION}
 
 clean:
 	rm -f git-absorb.1 git-absorb.xml

Documentation/README.md

@@ -1,7 +1,7 @@
 git-absorb manual
 =================
 
-This project's man page `git-absorb.1` can be generated from `git-absorb.txt`
+This project's man page `git-absorb.1` can be generated from `git-absorb.adoc`
 by running `make`.
 
 Build dependencies

Documentation/git-absorb.txt renamed to Documentation/git-absorb.adoc

@@ -53,6 +53,10 @@ FLAGS
 --force-author::
         Generate fixups to commits not made by you
 
+-F::
+--one-fixup-per-commit::
+        Only generate one fixup per commit
+
 -f::
 --force::
         Skip all safety checks.
@@ -82,6 +86,10 @@ OPTIONS
 --base <base>::
         Use this commit as the base of the absorb stack
 
+--gen-completions <SHELL>::
+        Generate completions
+        [possible values: bash, fish, nushell, zsh, powershell, elvish]
+
 USAGE
 -----
 
@@ -94,18 +102,14 @@ SHA of the commit it should be squashed into.
 
 3. If you are satisfied with the output, `git rebase -i --autosquash` to
 squash the `fixup!` commits into their predecessors. You can set the
-[GIT_SEQUENCE_EDITOR][] environment variable if you don't need to edit
-the rebase TODO file.
+https://stackoverflow.com/a/29094904[GIT_SEQUENCE_EDITOR] environment
+variable if you don't need to edit the rebase TODO file.
 
 4. If you are not satisfied (or if something bad happened), `git reset
 --soft` to the pre-absorption commit to recover your old state. (You can
-find the commit in question with `git reflog`.) And if you think `git
-absorb` is at fault, please [file an issue][].
-
-.............................................................................
-[GIT_SEQUENCE_EDITOR]: https://stackoverflow.com/a/29094904
-[file an issue]: https://github.com/tummychow/git-absorb/issues/new
-.............................................................................
+find the commit in question with `git reflog`.) And if you think
+`git absorb` is at fault, please
+https://github.com/tummychow/git-absorb/issues/new[file an issue].
 
 CONFIGURATION
 -------------
@@ -128,6 +132,49 @@ edit your local or global `.gitconfig` and add the following section:
     maxStack=50 # Or any other reasonable value for your project
 .............................................................................
 
+ONE FIXUP PER FIXABLE COMMIT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, git-absorb will generate separate fixup commits for every
+absorbable hunk. To always generate only 1 fixup commit for all hunks that
+absorb into the same commit, edit your local or global `.gitconfig` and add
+the following section:
+
+.............................................................................
+[absorb]
+    oneFixupPerCommit = true
+.............................................................................
+
+AUTO-STAGE ALL CHANGES IF NOTHING STAGED
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, git-absorb will only consider files that you've staged to the index
+via `git add`. However, sometimes one wants to try and absorb from all changes,
+which would require to stage them first via `git add .`. To avoid this extra
+step, set
+
+.............................................................................
+[absorb]
+    autoStageIfNothingStaged = true
+.............................................................................
+
+which tells git-absorb, when no changes are staged, to auto-stage them all,
+create fixup commits where possible, and unstage remaining changes from the
+index.
+
+FIXUP TARGET ALWAYS SHA
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, git-absorb will create fixup commits with their messages pointing
+to the target commit's summary, and if there are duplicate summaries, will
+fall back to pointing to the target's SHA. Instead, can always point to the
+target's SHA via:
+
+.............................................................................
+[absorb]
+    fixupTargetAlwaysSHA = true
+.............................................................................
+
 GENERATE FIXUPS FOR COMMITS NOT AUTHORED BY YOU
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

README.md

@@ -93,63 +93,11 @@ Note: `cargo install` does not currently know how to install manpages ([cargo#27
 
 For each hunk in the index, `git absorb` will check if that hunk commutes with the last commit, then the one before that, etc. When it finds a commit that does not commute with the hunk, it infers that this is the right parent commit for this change, and the hunk is turned into a fixup commit. If the hunk commutes with all commits in the range, it means we have not found a suitable parent commit for this change; a warning is displayed, and this hunk remains uncommitted in the index. 
 
-## Configuration
+## Documentation
 
-### Stack size
+For additional information about git-absorb, including all arguments and configuration options, see [Documentation/git-absorb.adoc](Documentation/git-absorb.adoc),
+or the git-absorb manual page.
 
-When run without `--base`, git-absorb will only search for candidate commits to fixup within a certain range (by default 10). If you get an error like this:
-
-```
-WARN stack limit reached, limit: 10
-```
-
-edit your local or global `.gitconfig` and add the following section
-
-```ini
-[absorb]
-    maxStack=50 # Or any other reasonable value for your project
-```
-
-### Generate fixups for commits not authored by you
-
-By default, git-absorb will only generate fixup commits for commits that were authored by you.
-Instead, use the `--force-author` flag to generate fixup commits for commits written by any author.
-To always have this behavior, set
-
-```ini
-[absorb]
-    forceAuthor = true
-```
-
-### One fixup per fixable commit
-
-By default, git-absorb will generate separate fixup commits for every absorbable hunk. Instead, can use the `-F` flag to create only 1 fixup commit for all hunks that absorb into the same commit.
-To always have this behavior, set
-
-```ini
-[absorb]
-    oneFixupPerCommit = true
-```
-
-### Auto-stage all changes if nothing staged
-
-By default, git-absorb will only consider files that you've staged to the index via `git add`. However, sometimes one wants to try and absorb from all changes, which would require to stage them first via `git add .`. To avoid this extra step, set
-
-```ini
-[absorb]
-    autoStageIfNothingStaged = true
-```
-
-which tells git-absorb, when no changes are staged, to auto-stage them all, create fixup commits where possible, and unstage remaining changes from the index.
-
-### Fixup target always SHA
-
-By default, git-absorb will create fixup commits with their messages pointing to the target commit's summary, and if there are duplicate summaries, will fallback to pointing to the target's SHA. Instead, can always point to the target's SHA via:
-
-```ini
-[absorb]
-    fixupTargetAlwaysSHA = true
-```
 
 ## TODO
 

src/main.rs

@@ -30,7 +30,7 @@ struct Cli {
     #[clap(long, short = 'r')]
     and_rebase: bool,
     /// Generate completions
-    #[clap(long, value_parser = ["bash", "fish", "nushell", "zsh", "powershell", "elvish"])]
+    #[clap(long, value_name = "SHELL", value_parser = ["bash", "fish", "nushell", "zsh", "powershell", "elvish"])]
     gen_completions: Option<String>,
     /// Match the change against the complete file
     #[clap(long, short)]