til-rb 0.0.3 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36329998af769fde62b800136de45304100925992f85d14463a127070da4b66d
-  data.tar.gz: e0283b08a1145176a3e6b7ea6e77dc65f4030f86571d7db3f6b475a3085213fa
+  metadata.gz: 59a21e1f498c47b6ee14766f23b04d3a75297abf4cf4871ee35ae22307455b54
+  data.tar.gz: 501c6ad1040355ce2e96f9209d65eb8489e52ffbe21d4e8a43b5294dd3adf0b0
 SHA512:
-  metadata.gz: '092def75bd54793b9318dc91a0b58bf3a6b09a488100daa0320bf97882f6fa94c6b84686aaf54c12e5bf51b662cc322b41de9a0a62c7e2fd2bd66732d3e80780'
-  data.tar.gz: 3d241da839314e320055bf5c2e717017f57deafdf2a9f3463a8174ccd4a846df3afa68c9f2601669ab5b54cd8aa034c0d864a68dff6d0a7e0136c0d48d199953
+  metadata.gz: eeee1045a7652efbf9de6793e5f03895a790f22e9ebd8fd634d59fa71a3d42ae050c3aa1b6a6d4b83e8a9f299ee33a52527f06ce8aadf9bce9d556f78c4fa044
+  data.tar.gz: ce2e02df0edf57fc1c9cd9d1b6ae73c2d32ec1f6ba8a00b7fa3cd46d2913823a18eeadecd7178e26b158618de13b967f725965a365db94c1bb319ac9319cb95f

data/README.md

@@ -5,3 +5,69 @@
 A work-in-progress tool to maintain a TIL repo.
 
 Inspiration: https://github.com/jbranchaud/til
+
+See it in action below:
+
+![til in action](til.gif)
+
+## Installation
+
+### Step 1: Install the gem
+
+```
+gem install til-rb
+```
+
+You will also need `fzf` to run `til`, it's available on homebrew, so unless you already installed it, you'll have to run
+
+```
+brew install fzf
+```
+
+_fzf is technically not a hard requirement, we really could have a slightly different workflow if it's not available.
+Given that I currently am the only user, there's no need to change this at the moment, but if you'd like to use this
+gem without `fzf`, let me know and I'll happily work on it!_
+
+### Step 2: Create a GitHub repo
+
+You need a GitHub repo to store your TILs. The gem has pretty strict expectations about the format of the README.md
+file, so I recommend forking [this repo](https://github.com/pjambet/til-template), or just copying the content to a
+fresh new repo.
+
+Note: The format expectations mentioned above are the following:
+
+- A "categories" section as defined by a leading markdown separator `---`, followed by a blank line, the `###
+  Categories` title, and a list of all the categories.
+- A links section as defined by a leading markdown separator `---`, followed by a blank line and a series of markdown
+  titles for each categories present in the previous section.
+
+### Step 3: Add the environment variables
+
+Add the following variables to your environment:
+
+- `TIL_RB_GITHUB_TOKEN`: The only required scope is `public_repo` if your TIL repo is public and `repo` if it is private. You can
+  create a token [in the GitHub
+  settings](https://github.com/settings/tokens/new?scopes=public_repo&description=Token%20for%20til-rb)
+- `TIL_RB_GITHUB_REPO`: The repo name, e.g. `pjambet/til`
+
+You might want to add those to either your `.bashrc` or `.zshrc` but please be careful in case you share those publicly
+as the token is private and *must not* be shared publicly.
+
+Note: An earlier version of this gem used different names, `GH_TOKEN` & `GH_REPO`, it still works, but is not the
+recommended approach anymore, see #2.
+
+### Step 4:
+
+Run `til` from the command line
+
+## Future improvements
+
+- An `init` command that will create a repo for you
+- A `configure` command that will store the token and the repo name in a file in `~/.config/til/config` or `~/.til`
+
+## Known issues
+
+The current version (0.0.5) deletes the temporary file before attempting to create the new commit, so if anything goes
+wrong there, the content of the file will be lost.
+This will be fixed soon, by only deleting the temporary file after the commit was created, but please keep that in mind
+if you typed a long TIL and definitely don't want to lose its content.

data/bin/til

@@ -1,5 +1,20 @@
 #!/usr/bin/env ruby
 
 require 'til-rb'
+require 'optparse'
 
-Til::Core.run
+options = {}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: til [options]'
+
+  opts.on('-t', '--title=TITLE', 'Set the title from the command line') do |title|
+    options[:title] = title
+  end
+
+  opts.on('-h', '--help', 'Prints this help') do
+    puts opts
+    exit
+  end
+end.parse!
+
+Til::Core.run options: options

data/lib/til/core.rb

@@ -5,7 +5,10 @@ require 'readline'
 module Til
   class Core
 
-    def self.run
+    GH_TOKEN_ENV_VAR_NAME = 'TIL_RB_GITHUB_TOKEN'
+    GH_REPO_ENV_VAR_NAME = 'TIL_RB_GITHUB_REPO'
+
+    def self.run(options: {})
       # Exit if `fzf` is not available
       # Optionally print a spinner
       # Grab the list of existing categories
@@ -18,17 +21,18 @@ module Til
       # Create the new file
       # Create a new commit
       # Output a link to the file and the link to edit it
-      til = new
+      til = new(options: options)
       til.run
     end
 
-    def initialize(kernel: Kernel, process: Process, env: ENV, github_client: nil, stderr: $stderr)
+    def initialize(options: {}, kernel: Kernel, process: Process, env: ENV, github_client: nil, stderr: $stderr)
+      @options = options
       @kernel = kernel
       @process = process
       @env = env
       @stderr = stderr
       @github_client = github_client
-      @repo_name = 'pjambet/til'
+      @repo_name = nil
       @new_category = false
     end
 
@@ -41,7 +45,7 @@ module Til
         if @new_category
           selected_category = prompt_for_new_category
         end
-        prepopulate_tempfile(selected_category)
+        prepopulate_tempfile(selected_category, @options[:title])
         open_editor
         til_content = read_file
         commit_new_til(selected_category, til_content)
@@ -58,17 +62,25 @@ module Til
     end
 
     def check_environment_variables
-      if @env['GH_TOKEN'].nil? || @env['GH_TOKEN'] == ''
-        raise 'The GH_TOKEN (with the public_repo or repo scope) environment variable is required'
+      if @env[GH_TOKEN_ENV_VAR_NAME].nil? || @env[GH_TOKEN_ENV_VAR_NAME] == ''
+        if @env['GH_TOKEN'].nil? || @env['GH_TOKEN'] == ''
+          raise "The #{GH_TOKEN_ENV_VAR_NAME} (with the public_repo or repo scope) environment variable is required"
+        else
+          @stderr.puts "Using GH_TOKEN is deprecated, use #{GH_TOKEN_ENV_VAR_NAME} instead"
+        end
       end
 
-      if (@env['VISUAL'].nil? || @env['VISUAL'] == '') && (@env['EDITOR'].nil? || @env['EDITOR'] == '')
-        raise 'The VISUAL or EDITOR environment variables are required'
+      if @env[GH_REPO_ENV_VAR_NAME].nil? || @env[GH_REPO_ENV_VAR_NAME] == ''
+        if @env['GH_REPO'].nil? || @env['GH_REPO'] == ''
+          raise "The #{GH_REPO_ENV_VAR_NAME} environment variable is required"
+        else
+          @stderr.puts "Using GH_REPO is deprecated, use #{GH_REPO_ENV_VAR_NAME} instead"
+        end
       end
     end
 
     def fetch_existing_categories
-      existing_categories = github_client.contents(@repo_name, path: '').filter do |c|
+      existing_categories = github_client.contents(repo_name, path: '').filter do |c|
         c['type'] == 'dir'
       end
 
@@ -80,7 +92,11 @@ module Til
     end
 
     def github_client
-      @github_client ||= Octokit::Client.new(access_token: @env['GH_TOKEN'])
+      @github_client ||= Octokit::Client.new(access_token: @env[GH_TOKEN_ENV_VAR_NAME] || @env['GH_TOKEN'])
+    end
+
+    def repo_name
+      @repo_name ||= (@env[GH_REPO_ENV_VAR_NAME] || @env['GH_REPO'])
     end
 
     def prompt_fzf(categories)
@@ -116,7 +132,7 @@ module Til
     end
 
     def open_editor
-      editor = ENV['VISUAL'] || ENV['EDITOR']
+      editor = ENV['VISUAL'] || ENV['EDITOR'] || 'vi'
       system(*editor.split, @tempfile.path)
     end
 
@@ -126,22 +142,26 @@ module Til
       content
     end
 
+    def new_filename(commit_title)
+      today = Time.now.strftime '%Y-%m-%d'
+      name = commit_title.split.map(&:downcase).join('-')
+      "#{today}_#{name}.md"
+    end
+
     def commit_new_til(category, content)
       commit_title = content.lines[0].chomp
       if commit_title.start_with?('#')
         commit_title = commit_title[1..].strip
       end
-      today = Time.now.strftime '%Y-%m-%d'
-      name = commit_title.split.map(&:downcase).join('-')
-      filename = "#{today}_#{name}.md"
+      filename = new_filename(commit_title)
 
-      ref = github_client.ref @repo_name, 'heads/master'
-      commit = github_client.commit @repo_name, ref.object.sha
-      tree = github_client.tree @repo_name, commit.commit.tree.sha, recursive: true
-      readme = github_client.readme @repo_name
+      ref = github_client.ref repo_name, 'heads/master'
+      commit = github_client.commit repo_name, ref.object.sha
+      tree = github_client.tree repo_name, commit.commit.tree.sha, recursive: true
+      readme = github_client.readme repo_name
       readme_content = Base64.decode64 readme.content
 
-      blob = github_client.create_blob @repo_name, content
+      blob = github_client.create_blob repo_name, content
       blobs = tree.tree.filter { |object|
         object[:type] == 'blob' && object[:path] != 'README.md'
       }.map { |object|
@@ -149,17 +169,20 @@ module Til
       }
 
       updated_readme_content = update_readme_content(category, commit_title, filename, readme_content)
-      new_readme_blob = github_client.create_blob @repo_name, updated_readme_content
+      new_readme_blob = github_client.create_blob repo_name, updated_readme_content
       blobs << { path: 'README.md', mode: '100644', type: 'blob', sha: new_readme_blob }
 
       blobs << { path: "#{category}/#{filename}", mode: '100644', type: 'blob', sha: blob }
 
-      tree = github_client.create_tree @repo_name, blobs
-      commit = github_client.create_commit @repo_name, commit_title, tree.sha, ref.object.sha
-      github_client.update_ref @repo_name, 'heads/master', commit.sha
+      tree = github_client.create_tree repo_name, blobs
+      commit = github_client.create_commit repo_name, commit_title, tree.sha, ref.object.sha
+      github_client.update_ref repo_name, 'heads/master', commit.sha
 
-      puts "You can see your new TIL at : https://github.com/pjambet/til/blob/master/#{category}/#{filename}"
-      puts "You can edit your new TIL at : https://github.com/pjambet/til/edit/master/#{category}/#{filename}"
+      cgi_escaped_filename = CGI.escape(filename)
+      til_url = "https://github.com/#{repo_name}/blob/master/#{category}/#{cgi_escaped_filename}"
+      til_edit_url = "https://github.com/#{repo_name}/edit/master/#{category}/#{cgi_escaped_filename}"
+      puts "You can see your new TIL at : #{til_url}"
+      puts "You can edit your new TIL at : #{til_edit_url}"
     end
 
     def update_readme_content(category, commit_title, filename, readme_content)

data/lib/til/readme_updater.rb

@@ -17,7 +17,7 @@ module Til
       loc_in_page = @initial_content.index("### #{existing_cat[1]}")
       next_cat_location = @initial_content.index('###', loc_in_page + 1)
 
-      new_line = "- [#{item_title}](#{category}/#{filename})"
+      new_line = "- [#{item_title}](#{category}/#{CGI.escape(filename)})"
       new_readme_content = ''
       if next_cat_location
         breakpoint = next_cat_location - 2
@@ -64,7 +64,7 @@ module Til
 
       next_bound = @initial_content.index('###', current_search_index + 1)
 
-      new_line = "- [#{item_title}](#{category}/#{filename})"
+      new_line = "- [#{item_title}](#{category}/#{CGI.escape(filename)})"
 
       if next_bound
         new_readme_content = @initial_content[0..(first_dashdashdash + 2)] \

data/lib/til/version.rb

@@ -1,5 +1,5 @@
 module Til
 
-  VERSION = '0.0.3'
+  VERSION = '0.0.8'
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: til-rb
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.8
 platform: ruby
 authors:
 - Pierre Jambet
@@ -66,7 +66,7 @@ files:
 - lib/til/core.rb
 - lib/til/readme_updater.rb
 - lib/til/version.rb
-homepage: https://rubygems.org/gems/til-rb
+homepage: https://github.com/pjambet/til-rb/
 licenses:
 - MIT
 metadata: {}