From 68f3b4d3c12330148deb90a6ee1e574dd943d342 Mon Sep 17 00:00:00 2001 From: Takuya Noguchi Date: Tue, 3 Jan 2023 23:00:08 +0000 Subject: [PATCH 1/2] Rewrite git guide from HAML to Markdown Signed-off-by: Takuya Noguchi --- source/guides/git.html.haml | 197 ------------------------------------ source/guides/git.html.md | 189 ++++++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+), 197 deletions(-) delete mode 100644 source/guides/git.html.haml create mode 100644 source/guides/git.html.md diff --git a/source/guides/git.html.haml b/source/guides/git.html.haml deleted file mode 100644 index 33bf0d5ebd..0000000000 --- a/source/guides/git.html.haml +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: How to install gems from git repositories ---- -.container.guide - %h2 How to install gems from git repositories - - .contents - .bullet - .description - %p - This document is written for Bundler 2.1 or higher. - Use `bundle config X Y` instead of `bundle config set X Y` - if you are still using Bundler 2.0 or earlier, which were already deprecated. - %p - Bundler has the ability to install gems directly from git repositories. Installing - a gem using git is as easy as adding a gem to your Gemfile. - %p - Note that because RubyGems lacks the ability to handle gems from git, any gems - installed from a git repository will not show up in gem list. - They will, however, be available after running Bundler.setup. - - .bullet - .description - Specify that a gem should come from a git - repository with a .gemspec at its root - :code - # lang: ruby - gem 'rack', git: 'https://github.com/rack/rack' - .bullet - .description - If there is no .gemspec at the root of - a git repository, you must specify a version - that bundler should use when resolving - dependencies - :code - # lang: ruby - gem 'nokogiri', '1.7.0.1', git: 'https://github.com/sparklemotion/nokogiri' - .bullet - .description - If the gem is located within a subdirectory of - a git repository, you can use the :glob option - to specify the location of its .gemspec - :code - # lang: ruby - gem 'cf-copilot', git: 'https://github.com/cloudfoundry/copilot', glob: 'sdk/ruby/*.gemspec' - .bullet - .description - Specify that a git repository containing - multiple .gemspec files should be treated - as a gem source - :code - # lang: ruby - git 'https://github.com/rails/rails.git' do - gem 'railties' - gem 'actionpack' - gem 'activemodel' - end - .bullet - .description - From the previous example, you may specify a particular ref, branch or tag - :code - # lang: ruby - git 'https://github.com/rails/rails.git', ref: '4aded' do - git 'https://github.com/rails/rails.git', branch: '5-0-stable' do - git 'https://github.com/rails/rails.git', tag: 'v5.0.0' do - .bullet - .description - Specifying a ref, branch, or tag for a - git repository specified inline works - exactly the same way - :code - # lang: ruby - gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', ref: '0bd839d' - gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', tag: '2.0.1' - gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', branch: 'rack-1.5' - .bullet - .description - Bundler can use HTTP(S), SSH, or git - :code - # lang: ruby - gem 'rack', git: 'https://github.com/rack/rack.git' - gem 'rack', git: 'git@github.com:rack/rack.git' - gem 'rack', git: 'git://github.com/rack/rack.git' - .bullet - .description - Specify that the submodules from a git repository - also should be expanded by bundler - :code - # lang: ruby - gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true - .bullet - .description - If you are getting your gems from a public GitHub repository, - you can use the shorthand - :code - # lang: ruby - gem 'rack', github: 'rack/rack' - .description - If the repository name is the same as the GitHub account hosting it, - you can omit it - :code - # lang: ruby - gem 'rails', github: 'rails' - .description - NB: This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write: - :code - # lang: ruby - gem 'rails', git: 'https://github.com/rails/rails' - .description - All of the usual :git options apply, like :branch and :ref. - :code - # lang: ruby - gem 'rails', github: 'rails', ref: 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56' - .description - There are analogous shortcuts for Bitbucket (:bitbucket) and GitHub Gists (:gist). - :code - # lang: ruby - gem 'keystone', bitbucket: 'musicone/keystone' - gem 'my_gist', gist: '4815162342' - %h2 Custom git sources - .contents - .bullet - .description - The :github shortcut used above is one of Bundler's built in git sources. Bundler comes - with shortcuts for :github, :gist, and :bitbucket, but you can - also add your own. - - .description - If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts - by calling git_source before you use your custom option. Here's an example for Stash: - - :code - # lang: ruby - git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" } - gem 'rails', stash: 'forks/rails' - %h2 Security - .contents - .bullet - .description - http:// and git:// URLs are insecure. A - man-in-the-middle attacker could tamper with the code as you check it out, - and potentially supply you with malicious code instead of the code you meant to - check out. Because the :github shortcut uses a git:// - URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding - the :github shortcut with your own HTTPS git source. - - %h2#local Local Git Repos - .contents - .bullet - .description - Bundler also allows you to work against a git repository locally - instead of using the remote version. This can be achieved by setting - up a local override: - :code - $ bundle config set local.GEM_NAME /path/to/local/git/repository - .bullet - .description - For example, in order to use a local Rack repository, a developer could call: - :code - $ bundle config set local.rack ~/Work/git/rack - .description - and setup the git repo pointing to a branch: - :code - # lang: ruby - gem 'rack', github: 'rack/rack', branch: 'master' - .bullet - .description - %p - Now instead of checking out the remote git repository, the local - override will be used. Similar to a path source, every time the local - git repository change, changes will be automatically picked up by - Bundler. This means a commit in the local git repo will update the - revision in the Gemfile.lock to the local git repo revision. This - requires the same attention as git submodules. Before pushing to - the remote, you need to ensure the local override was pushed, otherwise - you may point to a commit that only exists in your local machine. - - %p - Please note! - Bundler does many checks to ensure a developer won't work with - invalid references. Particularly, we force a developer to specify - a branch in the Gemfile in order to use this feature. If the branch - specified in the Gemfile and the current branch in the local git - repository do not match, Bundler will abort. This ensures that - a developer is always working against the correct branches, and prevents - accidental locking to a different branch. - - %p - Finally, Bundler also ensures that the current revision in the - Gemfile.lock exists in the local git repository. By doing this, Bundler - forces you to fetch the latest changes in the remotes. - - .bullet - .description - %p If you do not want bundler to make these branch checks, you can override it by setting this option: - :code - $ bundle config set disable_local_branch_check true diff --git a/source/guides/git.html.md b/source/guides/git.html.md new file mode 100644 index 0000000000..c93bc4626a --- /dev/null +++ b/source/guides/git.html.md @@ -0,0 +1,189 @@ +--- +title: How to install gems from git repositories +--- +## How to install gems from git repositories + +This document is written for Bundler 2.1 or higher. +Use `bundle config X Y` instead of `bundle config set X Y` +if you are still using Bundler 2.0 or earlier, which were already deprecated. + +Bundler has the ability to install gems directly from git repositories. Installing +a gem using git is as easy as adding a gem to your Gemfile. + +Note that because RubyGems lacks the ability to handle gems from git, any gems +installed from a git repository will not show up in `gem list`. +They will, however, be available after running `Bundler.setup`. +Specify that a gem should come from a git +repository with a .gemspec at its root + +~~~ruby +gem 'rack', git: 'https://github.com/rack/rack' +~~~ + +If there is no .gemspec at the root of +a git repository, you must specify a version +that bundler should use when resolving +dependencies + +~~~ruby +gem 'nokogiri', '1.7.0.1', git: 'https://github.com/sparklemotion/nokogiri' +~~~ + +If the gem is located within a subdirectory of +a git repository, you can use the `:glob` option +to specify the location of its .gemspec + +~~~ruby +gem 'cf-copilot', git: 'https://github.com/cloudfoundry/copilot', glob: 'sdk/ruby/*.gemspec' +~~~ + +Specify that a git repository containing +multiple .gemspec files should be treated +as a gem source + +~~~ruby +git 'https://github.com/rails/rails.git' do + gem 'railties' + gem 'actionpack' + gem 'activemodel' +end +~~~ + +From the previous example, you may specify a particular ref, branch or tag + +~~~ruby +git 'https://github.com/rails/rails.git', ref: '4aded' do +git 'https://github.com/rails/rails.git', branch: '5-0-stable' do +git 'https://github.com/rails/rails.git', tag: 'v5.0.0' do +~~~ + +Specifying a ref, branch, or tag for a +git repository specified inline works +exactly the same way + +~~~ruby +gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', ref: '0bd839d' +gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', tag: '2.0.1' +gem 'nokogiri', git: 'https://github.com/sparklemotion/nokogiri.git', branch: 'rack-1.5' +~~~ + +Bundler can use HTTP(S), SSH, or git + +~~~ruby +gem 'rack', git: 'https://github.com/rack/rack.git' +gem 'rack', git: 'git@github.com:rack/rack.git' +gem 'rack', git: 'git://github.com/rack/rack.git' +~~~ + +Specify that the submodules from a git repository +also should be expanded by bundler + +~~~ruby +gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true +~~~ + +If you are getting your gems from a public GitHub repository, +you can use the shorthand + +~~~ruby +gem 'rack', github: 'rack/rack' +~~~ + +If the repository name is the same as the GitHub account hosting it, +you can omit it + +~~~ruby +gem 'rails', github: 'rails' +~~~ + +*NB:* This shorthand can only be used for public repos in Bundler version 1.x. Use HTTPS for read and write: + +~~~ruby +gem 'rails', git: 'https://github.com/rails/rails' +~~~ + +All of the usual `:git` options apply, like `:branch` and `:ref`. + +~~~ruby +gem 'rails', github: 'rails', ref: 'a9752dcfd15bcddfe7b6f7126f3a6e0ba5927c56' +~~~ + +There are analogous shortcuts for Bitbucket (`:bitbucket`) and GitHub Gists (`:gist`). + +~~~ruby +gem 'keystone', bitbucket: 'musicone/keystone' +gem 'my_gist', gist: '4815162342' +~~~ + +## Custom git sources + +The `:github` shortcut used above is one of Bundler's built in git sources. Bundler comes +with shortcuts for `:github`, `:gist`, and `:bitbucket`, but you can +also add your own. +If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts +by calling `git_source` before you use your custom option. Here's an example for Stash: + +~~~ruby +git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" } +gem 'rails', stash: 'forks/rails' +~~~ + +## Security + +`http://` and `git://` URLs are insecure. A +man-in-the-middle attacker could tamper with the code as you check it out, +and potentially supply you with malicious code instead of the code you meant to +check out. Because the `:github` shortcut uses a `git://` +URL in Bundler 1.x versions, we recommend using HTTPS URLs or overriding +the `:github` shortcut with your own HTTPS git source. + +## Local Git Repos + + +Bundler also allows you to work against a git repository locally +instead of using the remote version. This can be achieved by setting +up a local override: + +~~~ +$ bundle config set local.GEM_NAME /path/to/local/git/repository +~~~ + +For example, in order to use a local Rack repository, a developer could call: + +~~~ +$ bundle config set local.rack ~/Work/git/rack +~~~ + +and setup the git repo pointing to a branch: + +~~~ruby +gem 'rack', github: 'rack/rack', branch: 'master' +~~~ + +Now instead of checking out the remote git repository, the local +override will be used. Similar to a path source, every time the local +git repository change, changes will be automatically picked up by +Bundler. This means a commit in the local git repo will update the +revision in the `Gemfile.lock` to the local git repo revision. This +requires the same attention as git submodules. Before pushing to +the remote, you need to ensure the local override was pushed, otherwise +you may point to a commit that only exists in your local machine. + +**Please note!** +Bundler does many checks to ensure a developer won't work with +invalid references. Particularly, **we force a developer to specify +a branch in the `Gemfile` in order to use this feature**. If the branch +specified in the `Gemfile` and the current branch in the local git +repository do not match, Bundler will abort. This ensures that +a developer is always working against the correct branches, and prevents +accidental locking to a different branch. + +Finally, Bundler also ensures that the current revision in the +`Gemfile.lock` exists in the local git repository. By doing this, Bundler +forces you to fetch the latest changes in the remotes. + +If you do not want bundler to make these branch checks, you can override it by setting this option: + +~~~ +$ bundle config set disable_local_branch_check true +~~~ From ff81541ba7b7d1b0595e4b05545e541155161ac5 Mon Sep 17 00:00:00 2001 From: Takuya N Date: Wed, 4 Jan 2023 10:18:44 +0900 Subject: [PATCH 2/2] Apply suggestions from code review --- source/guides/git.html.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/guides/git.html.md b/source/guides/git.html.md index c93bc4626a..50eeecf40b 100644 --- a/source/guides/git.html.md +++ b/source/guides/git.html.md @@ -13,6 +13,7 @@ a gem using git is as easy as adding a gem to your Gemfile. Note that because RubyGems lacks the ability to handle gems from git, any gems installed from a git repository will not show up in `gem list`. They will, however, be available after running `Bundler.setup`. + Specify that a gem should come from a git repository with a .gemspec at its root @@ -120,11 +121,12 @@ gem 'my_gist', gist: '4815162342' The `:github` shortcut used above is one of Bundler's built in git sources. Bundler comes with shortcuts for `:github`, `:gist`, and `:bitbucket`, but you can also add your own. + If you're using Github Enterprise, Stash, or just have a custom git setup, create your own shortcuts by calling `git_source` before you use your custom option. Here's an example for Stash: ~~~ruby -git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/\#{repo_name}.git" } +git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" } gem 'rails', stash: 'forks/rails' ~~~