gemstash 2.7.1 → 2.8.1

data/lib/gemstash/man/gemstash-private-gems.7

@@ -1,8 +1,23 @@
-<!-- Automatically generated by Pandoc -->
-.\" Automatically generated by Pandoc 3.1.8
+.\" Automatically generated by Pandoc 3.1.3
 .\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
 .TH "gemstash-private-gems" "7" "October 8, 2015" "" ""
+.hy
 .SH Private Gems
+.PP
 Stashing private gems in your Gemstash server requires a bit of
 additional setup.
 If you haven\[cq]t read through the Quickstart Guide, you should do that
@@ -10,6 +25,7 @@ first.
 By the end of this guide, you will be able to interact with your
 Gemstash server to store and retrieve your private gems.
 .SS Authorizing
+.PP
 \f[B]IMPORTANT NOTE:\f[R] Do not use the actual key value in this
 document, otherwise your Gemstash server will be vulnerable to anyone
 who wants to try to use the key against your server.
@@ -18,32 +34,38 @@ running the commands.
 .PP
 In order to push a gem to your Gemstash server, you need to first create
 an API key.
-Utilize the \f[CR]gemstash authorize\f[R] command to create the API key:
+Utilize the \f[V]gemstash authorize\f[R] command to create the API key:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash authorize
 Your new key is: e374e237fdf5fa5718d2a21bd63dc911
-.EE
+\f[R]
+.fi
 .PP
-This new key can \f[CR]push\f[R], \f[CR]yank\f[R], and \f[CR]fetch\f[R]
+This new key can \f[V]push\f[R], \f[V]yank\f[R], and \f[V]fetch\f[R]
 gems from your Gemstash server.
-Run \f[CR]gemstash authorize\f[R] with just the permissions you want to
+Run \f[V]gemstash authorize\f[R] with just the permissions you want to
 limit what the key will be allowed to do.
 You can similarly update a specific key by providing it via the
-\f[CR]--key\f[R] option:
+\f[V]--key\f[R] option:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
-.EE
+\f[R]
+.fi
 .PP
 When no permissions are provided (like the first example), the key will
 be authorized for all permissions.
 Leave the key authorized with everything if you want to use it to try
 all private gem interactions:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
-.EE
+\f[R]
+.fi
 .PP
 With the key generated, you\[cq]ll need to tell Rubygems about your new
 key.
@@ -52,70 +74,86 @@ already have a credentials file to add the key to.
 If not, run the following commands before modifying the credentials
 file:
 .IP
-.EX
+.nf
+\f[C]
 $ mkdir -p \[ti]/.gem
 $ touch \[ti]/.gem/credentials
 $ chmod 0600 \[ti]/.gem/credentials
-.EE
+\f[R]
+.fi
 .PP
 Add your new key to credentials such that it looks something like this
 (but make sure not to remove any existing keys):
 .IP
-.EX
+.nf
+\f[C]
 # \[ti]/.gem/credentials
 ---
 :test_key: e374e237fdf5fa5718d2a21bd63dc911
-.EE
+\f[R]
+.fi
 .PP
-The name \f[CR]test_key\f[R] can be anything you want, but you will need
+The name \f[V]test_key\f[R] can be anything you want, but you will need
 to remember it and use it again later in this guide for the
-\f[CR]--key\f[R] option.
+\f[V]--key\f[R] option.
 .SS Creating a Test Gem
+.PP
 You\[cq]ll need a test gem before you can play with private gems on your
 Gemstash server.
 If you have a gem you can use, move along to the next section.
 You can start by instantiating a test gem via Bundler:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle gem private-example
-.EE
+\f[R]
+.fi
 .PP
 You\[cq]ll need to add a summary and description to the new gem\[cq]s
 gemspec file in order to successfully build it.
 Once you\[cq]ve built the gem, you will be ready to push the new gem.
 .IP
-.EX
+.nf
+\f[C]
 $ cd private-example
 $ rake build
-.EE
+\f[R]
+.fi
 .PP
 You will now have a gem at
-\f[CR]private-example/pkg/private-example-0.1.0.gem\f[R].
+\f[V]private-example/pkg/private-example-0.1.0.gem\f[R].
 .SS Pushing
+.PP
 If your Gemstash server isn\[cq]t running, go ahead and start it:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash start
-.EE
+\f[R]
+.fi
 .PP
 Push your test gem using Rubygems:
 .IP
-.EX
+.nf
+\f[C]
 $ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
-.EE
+\f[R]
+.fi
 .PP
-The \f[CR]/private\f[R] portion of the \f[CR]--host\f[R] option tells
+The \f[V]/private\f[R] portion of the \f[V]--host\f[R] option tells
 Gemstash you are interacting with the private gems.
 Gemstash will not let you push, or yank from anything except
-\f[CR]/private\f[R].
+\f[V]/private\f[R].
 .SS Bundling
+.PP
 Once your gem is pushed to your Gemstash server, you are ready to bundle
 it.
-Create a \f[CR]Gemfile\f[R] and specify the gem.
+Create a \f[V]Gemfile\f[R] and specify the gem.
 You will probably want to wrap the private gem in a source block, and
 let the rest of Gemstash handle all other gems:
 .IP
-.EX
+.nf
+\f[C]
 # ./Gemfile
 source \[dq]http://localhost:9292\[dq]
 gem \[dq]rubywarrior\[dq]
@@ -123,55 +161,65 @@ gem \[dq]rubywarrior\[dq]
 source \[dq]http://localhost:9292/private\[dq] do
   gem \[dq]private-example\[dq]
 end
-.EE
+\f[R]
+.fi
 .PP
-Notice that the Gemstash server points to \f[CR]/private\f[R] again when
+Notice that the Gemstash server points to \f[V]/private\f[R] again when
 installing your private gem.
 Go ahead and bundle to install your new private gem:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle
-.EE
+\f[R]
+.fi
 .SS Yanking
+.PP
 If you push a private gem by accident, you can yank the gem with
 Rubygems:
 .IP
-.EX
+.nf
+\f[C]
 $ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
-.EE
+\f[R]
+.fi
 .PP
-Like with pushing, the \f[CR]/private\f[R] portion of the host option
+Like with pushing, the \f[V]/private\f[R] portion of the host option
 tells Gemstash you are interacting with private gems.
-Gemstash will only let you yank from \f[CR]/private\f[R].
-Unlike pushing, Rubygems doesn\[cq]t support \f[CR]--host\f[R] for yank
-(yet), so you need to specify the host via the \f[CR]RUBYGEMS_HOST\f[R]
+Gemstash will only let you yank from \f[V]/private\f[R].
+Unlike pushing, Rubygems doesn\[cq]t support \f[V]--host\f[R] for yank
+(yet), so you need to specify the host via the \f[V]RUBYGEMS_HOST\f[R]
 environment variable.
 .SS Protected Fetching
+.PP
 By default, private gems and specs can be accessed without
 authentication.
 .PP
 Private gems often require protected fetching.
 For backwards compatibility this is disabled by default, but can be
-enabled via \f[CR]$ gemstash setup\f[R] command.
+enabled via \f[V]$ gemstash setup\f[R] command.
 .PP
 When protected fetching is enabled API keys with the permissions
-\f[CR]all\f[R] or \f[CR]fetch\f[R] can be used to download gems and
-specs.
+\f[V]all\f[R] or \f[V]fetch\f[R] can be used to download gems and specs.
 .PP
 On the Bundler side, there are a few ways to configure credentials for a
 given gem source:
 .PP
 Add credentials globally:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle config my-gemstash.dev api_key
-.EE
+\f[R]
+.fi
 .PP
 Add credentials in Gemfile:
 .IP
-.EX
+.nf
+\f[C]
 source \[dq]https://api_key\[at]my-gemstash.dev\[dq]
-.EE
+\f[R]
+.fi
 .PP
 However, it\[cq]s not a good practice to commit credentials to source
 control.
@@ -179,13 +227,15 @@ A recommended solution is to use Bundler\[cq]s configuration
 keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS),
 e.g.:
 .IP
-.EX
+.nf
+\f[C]
 $ export BUNDLE_MYGEMSTASH__DEV=api_key
-.EE
+\f[R]
+.fi
 .PP
 Behind the scene, Bundler will pick up the ENV var according to the host
-name (e.g.\ mygemstash.dev) and add to \f[CR]URI.userinfo\f[R] for
-making requests.
+name (e.g.\ mygemstash.dev) and add to \f[V]URI.userinfo\f[R] for making
+requests.
 .PP
 The API key is treated as a HTTP Basic Auth username and any HTTP Basic
 password supplied will be ignored.

data/lib/gemstash/man/gemstash-private-gems.7.txt

@@ -1,12 +1,10 @@
 4mgemstash-private-gems24m(7)				   4mgemstash-private-gems24m(7)
 
-<!-- Automatically generated by Pandoc -->
-
 1mPrivate Gems0m
-       Stashing  private  gems in your Gemstash server requires a bit of addi-
+       Stashing	 private  gems in your Gemstash server requires a bit of addi-
        tional setup.  If you haven't read through the  Quickstart  Guide,  you
-       should  do  that  first.  By the end of this guide, you will be able to
-       interact with your Gemstash server to store and retrieve  your  private
+       should  do  that	 first.	 By the end of this guide, you will be able to
+       interact with your Gemstash server to store and retrieve	 your  private
        gems.
 
    1mAuthorizing0m
@@ -16,28 +14,28 @@
        use whatever key is generated from running the commands.
 
        In  order to push a gem to your Gemstash server, you need to first cre-
-       ate an API key.	Utilize the gemstash authorize command to  create  the
+       ate an API key.	Utilize the 1mgemstash authorize 22mcommand to	create	the
        API key:
 
 	      $ gemstash authorize
 	      Your new key is: e374e237fdf5fa5718d2a21bd63dc911
 
-       This  new key can push, yank, and fetch gems from your Gemstash server.
-       Run gemstash authorize with just the permissions you want to limit what
+       This  new key can 1mpush22m, 1myank22m, and 1mfetch 22mgems from your Gemstash server.
+       Run 1mgemstash authorize 22mwith just the permissions you want to limit what
        the key will be allowed to do.  You can similarly update a specific key
-       by providing it via the --key option:
+       by providing it via the 1m--key 22moption:
 
 	      $ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
 
        When no permissions are provided (like the first example), the key will
-       be authorized for all  permissions.   Leave  the  key  authorized  with
+       be authorized for all  permissions.   Leave  the	 key  authorized  with
        everything if you want to use it to try all private gem interactions:
 
 	      $ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
 
        With  the  key  generated,  you'll need to tell Rubygems about your new
        key.  If you've pushed a gem to https://rubygems.org, then you will al-
-       ready have a credentials file to add the key to.  If not, run the  fol-
+       ready have a credentials file to add the key to.	 If not, run the  fol-
        lowing commands before modifying the credentials file:
 
 	      $ mkdir -p ~/.gem
@@ -51,13 +49,13 @@
 	      ---
 	      :test_key: e374e237fdf5fa5718d2a21bd63dc911
 
-       The name test_key can be anything you want, but you will need to remem-
-       ber it and use it again later in this guide for the --key option.
+       The name 1mtest_key 22mcan be anything you want, but you will need to remem-
+       ber it and use it again later in this guide for the 1m--key 22moption.
 
    1mCreating a Test Gem0m
        You'll need a test gem before you can play with private	gems  on  your
-       Gemstash server.  If you have a gem you can use, move along to the next
-       section.  You can start by instantiating a test gem via Bundler:
+       Gemstash server.	 If you have a gem you can use, move along to the next
+       section.	 You can start by instantiating a test gem via Bundler:
 
 	      $ bundle gem private-example
 
@@ -68,8 +66,8 @@
 	      $ cd private-example
 	      $ rake build
 
-       You  will  now  have   a   gem	at   private-example/pkg/private-exam-
-       ple-0.1.0.gem.
+       You  will  now  have   a	  gem	at   1mprivate-example/pkg/private-exam-0m
+       1mple-0.1.0.gem22m.
 
    1mPushing0m
        If your Gemstash server isn't running, go ahead and start it:
@@ -80,13 +78,13 @@
 
 	      $ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
 
-       The /private portion of the --host option tells Gemstash you are inter-
+       The 1m/private 22mportion of the 1m--host 22moption tells Gemstash you are inter-
        acting  with the private gems.  Gemstash will not let you push, or yank
-       from anything except /private.
+       from anything except 1m/private22m.
 
    1mBundling0m
        Once your gem is pushed to your Gemstash server, you are ready to  bun-
-       dle  it.  Create a Gemfile and specify the gem.	You will probably want
+       dle  it.	 Create a 1mGemfile 22mand specify the gem.  You will probably want
        to wrap the private gem in a source block, and let the rest of Gemstash
        handle all other gems:
 
@@ -98,8 +96,8 @@
 		gem "private-example"
 	      end
 
-       Notice that the Gemstash server	points	to  /private  again  when  in-
-       stalling  your  private	gem.   Go ahead and bundle to install your new
+       Notice that the Gemstash server	points	to  1m/private	22magain  when	in-
+       stalling	 your  private	gem.   Go ahead and bundle to install your new
        private gem:
 
 	      $ bundle
@@ -110,22 +108,22 @@
 
 	      $ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
 
-       Like  with  pushing, the /private portion of the host option tells Gem-
+       Like  with  pushing, the 1m/private 22mportion of the host option tells Gem-
        stash you are interacting with private gems.  Gemstash  will  only  let
-       you  yank  from	/private.   Unlike  pushing,  Rubygems doesn't support
-       --host for yank (yet),  so  you	need  to  specify  the	host  via  the
-       RUBYGEMS_HOST environment variable.
+       you  yank  from	1m/private22m.	 Unlike	 pushing,  Rubygems doesn't support
+       1m--host 22mfor yank (yet),  so	you  need  to  specify	the  host  via	the
+       1mRUBYGEMS_HOST 22menvironment variable.
 
    1mProtected Fetching0m
        By  default, private gems and specs can be accessed without authentica-
        tion.
 
        Private gems often require protected fetching.  For backwards  compati-
-       bility  this  is disabled by default, but can be enabled via $ gemstash
-       setup command.
+       bility  this  is disabled by default, but can be enabled via 1m$ gemstash0m
+       1msetup 22mcommand.
 
-       When protected fetching is enabled API keys with the permissions all or
-       fetch can be used to download gems and specs.
+       When protected fetching is enabled API keys with the permissions 1mall 22mor
+       1mfetch 22mcan be used to download gems and specs.
 
        On the Bundler side, there are a few ways to configure credentials  for
        a given gem source:
@@ -138,17 +136,17 @@
 
 	      source "https://api_key@my-gemstash.dev"
 
-       However,  it's not a good practice to commit credentials to source con-
+       However,	 it's not a good practice to commit credentials to source con-
        trol.  A recommended solution is to use	Bundler's  configuration  keys
        (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.:
 
 	      $ export BUNDLE_MYGEMSTASH__DEV=api_key
 
        Behind  the  scene,  Bundler  will pick up the ENV var according to the
-       host name (e.g. mygemstash.dev) and add to URI.userinfo for making  re-
+       host name (e.g. mygemstash.dev) and add to 1mURI.userinfo 22mfor making	re-
        quests.
 
        The API key is treated as a HTTP Basic Auth username and any HTTP Basic
        password supplied will be ignored.
 
-				October 8, 2015       4mgemstash-private-gems24m(7)
+				October 8, 2015	      4mgemstash-private-gems24m(7)

data/lib/gemstash/man/gemstash-readme.7

@@ -1,9 +1,24 @@
-<!-- Automatically generated by Pandoc -->
-.\" Automatically generated by Pandoc 3.1.8
+.\" Automatically generated by Pandoc 3.1.3
 .\"
+.\" Define V font for inline verbatim, using C font in formats
+.\" that render this, and otherwise B font.
+.ie "\f[CB]x\f[]"x" \{\
+. ftr V B
+. ftr VI BI
+. ftr VB B
+. ftr VBI BI
+.\}
+.el \{\
+. ftr V CR
+. ftr VI CI
+. ftr VB CB
+. ftr VBI CBI
+.\}
 .TH "gemstash-readme" "7" "November 30, 2015" "" ""
+.hy
 .SH Gemstash
 .SS What is Gemstash?
+.PP
 Gemstash is both a cache for remote servers such as
 https://rubygems.org, and a private gem source.
 .PP
@@ -31,6 +46,7 @@ Bundler, RubyGems, Gemstash, and other shared tooling is around for
 years to come.
 .SS Quickstart Guide
 .SS Setup
+.PP
 Gemstash is designed to be quick and painless to get set up.
 By the end of this Quickstart Guide, you will be able to bundle stashed
 gems from public sources against a Gemstash server running on your
@@ -38,45 +54,56 @@ machine.
 .PP
 Install Gemstash to get started:
 .IP
-.EX
+.nf
+\f[C]
 $ gem install gemstash
-.EE
+\f[R]
+.fi
 .PP
 After it is installed, starting Gemstash requires no additional steps.
-Simply start the Gemstash server with the \f[CR]gemstash\f[R] command:
+Simply start the Gemstash server with the \f[V]gemstash\f[R] command:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash start
-.EE
+\f[R]
+.fi
 .PP
 You may have noticed that the command finished quickly.
 This is because Gemstash will run the server in the background by
 default.
 The server runs on port 9292.
 .SS Bundling
+.PP
 With the server running, you can bundle against it.
 Tell Bundler that you want to use Gemstash to find gems from
 RubyGems.org:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle config mirror.https://rubygems.org http://localhost:9292
-.EE
+\f[R]
+.fi
 .PP
 Now you can create a Gemfile and install gems through Gemstash:
 .IP
-.EX
+.nf
+\f[C]
 # ./Gemfile
 source \[dq]https://rubygems.org\[dq]
 gem \[dq]rubywarrior\[dq]
-.EE
+\f[R]
+.fi
 .PP
 The gems you include should be gems you don\[cq]t yet have installed,
 otherwise Gemstash will have nothing to stash.
 Now bundle:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle install --path .bundle
-.EE
+\f[R]
+.fi
 .PP
 Your Gemstash server has fetched the gems from https://rubygems.org and
 cached them for you!
@@ -86,52 +113,65 @@ Gem dependencies metadata are cached for 30 minutes, so if you bundle
 again before that, you can successfully bundle without an Internet
 connection:
 .IP
-.EX
+.nf
+\f[C]
 $ # Disable your Internet first!
 $ rm -rf Gemfile.lock .bundle
 $ bundle
-.EE
+\f[R]
+.fi
 .SS Falling back to rubygems.org
+.PP
 If you want to make sure that your bundling from https://rubygems.org
 still works as expected when the Gemstash server is not running, you can
 easily configure Bundler to fallback to https://rubygems.org.
 .IP
-.EX
+.nf
+\f[C]
 $ bundle config mirror.https://rubygems.org.fallback_timeout true
-.EE
+\f[R]
+.fi
 .PP
 You can also configure this fallback as a number of seconds in case the
 Gemstash server is simply unresponsive.
 This example uses a 3 second timeout:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle config mirror.https://rubygems.org.fallback_timeout 3
-.EE
+\f[R]
+.fi
 .SS Stopping the Server
+.PP
 Once you\[cq]ve finish using your Gemstash server, you can stop it just
 as easily as you started it:
 .IP
-.EX
+.nf
+\f[C]
 $ gemstash stop
-.EE
+\f[R]
+.fi
 .PP
 You\[cq]ll also want to tell Bundler that it can go back to getting gems
 from RubyGems.org directly, instead of going through Gemstash:
 .IP
-.EX
+.nf
+\f[C]
 $ bundle config --delete mirror.https://rubygems.org
-.EE
+\f[R]
+.fi
 .SS Under the Hood
+.PP
 You might wonder where the gems are stored.
 After running the commands above, you will find a new directory at
-\f[CR]\[ti]/.gemstash\f[R].
+\f[V]\[ti]/.gemstash\f[R].
 This directory holds all the cached and private gems.
 It also has a server log, the database, and configuration for Gemstash.
 If you prefer, you can point to a different directory.
 .PP
 Gemstash uses SQLite (https://www.sqlite.org/) to store details about
 private gems.
-The database will be located in \f[CR]\[ti]/.gemstash\f[R], however you
+The database will be located in \f[V]\[ti]/.gemstash\f[R], however you
 won\[cq]t see the database appear until you start using private gems.
 If you prefer, you can use a different database.
 .PP
@@ -140,13 +180,14 @@ Anything cached in memory will last for 30 minutes before being
 retrieved again.
 You can use memcached instead of caching in memory.
 Gem files are always cached permanently, so bundling with a
-\f[CR]Gemfile.lock\f[R] with all gems cached will never call out to
+\f[V]Gemfile.lock\f[R] with all gems cached will never call out to
 https://rubygems.org.
 .PP
 The server you ran is provided via Puma (https://puma.io/) and
 Rack (https://github.com/rack/rack), however they are not customizable
 at this point.
 .SS Deep Dive
+.PP
 Deep dive into more subjects:
 .IP \[bu] 2
 Private gems
@@ -161,6 +202,7 @@ Deploying Gemstash
 .IP \[bu] 2
 Debugging Gemstash
 .SS Reference
+.PP
 An anatomy of various configuration and commands:
 .IP \[bu] 2
 Configuration
@@ -180,13 +222,15 @@ Version
 To see what has changed in recent versions of Gemstash, see the
 CHANGELOG (https://github.com/rubygems/gemstash/blob/main/CHANGELOG.md).
 .SS Development
-After checking out the repo, run \f[CR]bin/setup\f[R] to install
+.PP
+After checking out the repo, run \f[V]bin/setup\f[R] to install
 dependencies.
-Then, run \f[CR]rake\f[R] to run RuboCop and the tests.
-While developing, you can run \f[CR]bin/gemstash\f[R] to run Gemstash.
-You can also run \f[CR]bin/console\f[R] for an interactive prompt that
+Then, run \f[V]rake\f[R] to run RuboCop and the tests.
+While developing, you can run \f[V]bin/gemstash\f[R] to run Gemstash.
+You can also run \f[V]bin/console\f[R] for an interactive prompt that
 will allow you to experiment.
 .SS Contributing
+.PP
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/rubygems/gemstash.
 This project is intended to be a safe, welcoming space for
@@ -195,5 +239,6 @@ Contributor
 Covenant (https://github.com/rubygems/gemstash/blob/main/CODE_OF_CONDUCT.md)
 code of conduct.
 .SS License
+.PP
 The gem is available as open source under the terms of the MIT
 License (http://opensource.org/licenses/MIT).