Skip to main content

Add documentation for my fish functions

ID
9692461
date
2024-01-16 23:13:41+00:00
author
Alex Chan <alex@alexwlchan.net>
parent
44b69ee
message
Add documentation for my fish functions
changed files
5 files, 171 additions, 45 deletions

Changed files

fish_functions/README.md (0) → fish_functions/README.md (3438)

diff --git a/fish_functions/README.md b/fish_functions/README.md
new file mode 100644
index 0000000..62d44ce
--- /dev/null
+++ b/fish_functions/README.md
@@ -0,0 +1,125 @@
+# fish_functions
+
+This is a collection of functions for the Fish shell, which are [automatically loaded][functions].
+When I call one of these functions for the first time, Fish looks for the corresponding file in this folder and loads the function from there.
+
+[functions]: https://fishshell.com/docs/current/language.html#autoloading-functions
+
+<!-- [[[cog
+
+# This adds the root of the repo to the PATH, which has cog_helpers.py
+from os.path import abspath, basename, dirname
+import sys
+
+sys.path.append(abspath(dirname(dirname("."))))
+
+import glob
+import shlex
+
+import cog
+
+import cog_helpers
+
+folder_name = "fish_functions"
+
+functions = []
+
+for f in sorted(glob.glob("fish_functions/*.fish")):
+
+    # Look for the line in the file that defines the function.
+    #
+    # e.g. if the file is called 'tmpdir.fish', look for the line that
+    # starts 'function tmpdir'
+    function_name = basename(f).replace('.fish', '')
+    definition_line = next(
+        line
+        for line in open(f)
+        if line.startswith(f'function {function_name}')
+    )
+
+    # Now split the definition line into components
+    components = shlex.split(definition_line)
+    try:
+        description_flag = components.index("--description")
+    except ValueError:
+        raise ValueError(f"No --description flag for {function_name}")
+    description = components[description_flag + 1]
+
+    functions.append({"name": basename(f), "description": description})
+
+cog_helpers.create_description_table(folder_name=folder_name, scripts=functions)
+]]] -->
+<dl>
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/append_to_file_if_not_exists.fish">
+      <code>append_to_file_if_not_exists.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Append a line to a file, but only if it's not already there
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/auto_activate_venv.fish">
+      <code>auto_activate_venv.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Auto activate/deactivate virtualenv when I change directories
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/fish_prompt.fish">
+      <code>fish_prompt.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Write out the prompt
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/forget_last_command.fish">
+      <code>forget_last_command.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Remove the last-typed command from my fish history
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/github-clone.fish">
+      <code>github-clone.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Clone a GitHub repository into my ~/repos directory
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/reload_fish_config.fish">
+      <code>reload_fish_config.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Load the latest version of my fish config
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/tmpdir.fish">
+      <code>tmpdir.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Create and switch into a temporary directory
+  </dd>
+
+  <dt>
+    <a href="https://github.com/alexwlchan/scripts/blob/main/fish_functions/venv.fish">
+      <code>venv.fish</code>
+    </a>
+  </dt>
+  <dd>
+    Create and activate a new virtual environment
+  </dd>
+</dl>
+<!-- [[[end]]] (checksum: 2416bf573658cad59a5851b6623b6b8c) -->
\ No newline at end of file

fish_functions/forget_last_command.fish (521) → fish_functions/forget_last_command.fish (588)

diff --git a/fish_functions/forget_last_command.fish b/fish_functions/forget_last_command.fish
index 3f2e225..0cae1f0 100644
--- a/fish_functions/forget_last_command.fish
+++ b/fish_functions/forget_last_command.fish
@@ -6,7 +6,7 @@
 #
 # See https://alexwlchan.net/2023/forgetful-fish/
 # See https://github.com/fish-shell/fish-shell/issues/10066
-function forget_last_command
+function forget_last_command --description "Remove the last-typed command from my fish history"
     set last_typed_command (history --max 1)
     history delete --exact --case-sensitive "$last_typed_command"
     history save

fish_functions/github-add-pr-branch.fish (1444) → fish_functions/github-add-pr-branch.fish (0)

diff --git a/fish_functions/github-add-pr-branch.fish b/fish_functions/github-add-pr-branch.fish
deleted file mode 100644
index 45bba91..0000000
--- a/fish_functions/github-add-pr-branch.fish
+++ /dev/null
@@ -1,41 +0,0 @@
-# Given a GitHub pull request, create the repo and make sure the remote
-# of the PR owner is added as a remote.
-#
-#     $1 = URL of the pull request
-#
-# Sometimes when I'm looking at a pull request, it's useful to get the
-# branch locally and test/review/squash it as appropriate.  This makes
-# it easier to do so!
-#
-# Typically not called directly, but detected by 'github-open' and
-# switched to if looking at a pull request URL.
-function github-add-pr-branch
-    # First ensure we have a local clone of the repo
-    set url "$argv[1]"
-    github-clone (string split "pull/" "$url" | head -n 1)
-    if [ $status != 0 ]
-        return 1
-    end
-
-    # Get the identifiers for the repository.  A pull request URL is
-    # of the form
-    #
-    #     https://github.com/:owner/:repo/pull/:number#discussion_:comment
-    #
-    set components (string split "/" "$url")
-
-    if [ "$components[6]" != pull ]
-        echo "$url is not a GitHub pull request"
-        return 1
-    end
-
-    set owner $components[4]
-    set repo $components[5]
-    set number (echo $components[7] | tr '#' ' ' | awk '{print $1}')
-
-    set api_url "https://api.github.com/repos/$owner/$repo/pulls/$number"
-    set api_resp (curl -s -H "Accept: application/vnd.github.v3+json" "$api_url")
-    set pr_branch (echo $api_resp | jq '.head.repo.full_name' | tr '"' ' ' | awk '{print $1}')
-
-    git checkout (echo $api_resp | jq '.head.ref' | tr '"' ' ' | awk '{print $1}')
-end

fish_functions/github-clone.fish (1938) → fish_functions/github-clone.fish (3451)

diff --git a/fish_functions/github-clone.fish b/fish_functions/github-clone.fish
index ef4ea03..0791d8d 100644
--- a/fish_functions/github-clone.fish
+++ b/fish_functions/github-clone.fish
@@ -4,7 +4,7 @@
 #
 # Because switching to the repo homepage, clicking, copying the clone URL,
 # typing 'git clone', pasting, are all more effort than I care to do manually.
-function github-clone
+function github-clone --description "Clone a GitHub repository into my ~/repos directory"
     set url "$argv[1]"
 
     # Get the identifiers for the repository
@@ -62,3 +62,45 @@ function github-clone
         echo .DS_Store >>.git/info/exclude
     end
 end
+
+# Given a GitHub pull request, create the repo and make sure the remote
+# of the PR owner is added as a remote.
+#
+#     $1 = URL of the pull request
+#
+# Sometimes when I'm looking at a pull request, it's useful to get the
+# branch locally and test/review/squash it as appropriate.  This makes
+# it easier to do so!
+#
+# Typically not called directly, but detected by 'github-open' and
+# switched to if looking at a pull request URL.
+function github-add-pr-branch
+    # First ensure we have a local clone of the repo
+    set url "$argv[1]"
+    github-clone (string split "pull/" "$url" | head -n 1)
+    if [ $status != 0 ]
+        return 1
+    end
+
+    # Get the identifiers for the repository.  A pull request URL is
+    # of the form
+    #
+    #     https://github.com/:owner/:repo/pull/:number#discussion_:comment
+    #
+    set components (string split "/" "$url")
+
+    if [ "$components[6]" != pull ]
+        echo "$url is not a GitHub pull request"
+        return 1
+    end
+
+    set owner $components[4]
+    set repo $components[5]
+    set number (echo $components[7] | tr '#' ' ' | awk '{print $1}')
+
+    set api_url "https://api.github.com/repos/$owner/$repo/pulls/$number"
+    set api_resp (curl -s -H "Accept: application/vnd.github.v3+json" "$api_url")
+    set pr_branch (echo $api_resp | jq '.head.repo.full_name' | tr '"' ' ' | awk '{print $1}')
+
+    git checkout (echo $api_resp | jq '.head.ref' | tr '"' ' ' | awk '{print $1}')
+end

fish_functions/reload_fish_config.fish (225) → fish_functions/reload_fish_config.fish (279)

diff --git a/fish_functions/reload_fish_config.fish b/fish_functions/reload_fish_config.fish
index 7e3256c..9e8e748 100644
--- a/fish_functions/reload_fish_config.fish
+++ b/fish_functions/reload_fish_config.fish
@@ -1,10 +1,10 @@
-function reload_fish_config
+function reload_fish_config --description "Load the latest version of my fish config"
     source ~/.config/fish/config.fish
 
     for file in $conf_dir/*.fish
         source "$file"
     end
-    
+
     for file in ~/repos/scripts/fish_functions/*.fish
         source "$file"
     end