Module: GitHub::Client::Contents

Included in:
GitHub::Client
Defined in:
lib/github_api_v3/client/contents.rb

Overview

Methods for the Contents API.

These methods allow the retrieval of contents of files within a repository as Base64 encoded content.

See Also:

Instance Method Summary collapse

Instance Method Details

#archive(owner, repo, format = 'zipball', ref = 'master') ⇒ String

Retrieve archive link.

Examples:

Retrieve download link.

GitHub.archive('caseyscarborough', 'github', 'tarball')
# => "https://codeload.github.com/caseyscarborough/github/legacy.tar.gz/master"

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • format (String) (defaults to: 'zipball') —

    Archive type. zipball (default) or tarball.

  • ref (String) (defaults to: 'master') —

    Valid Git reference, defaults to master.

Returns:

  • (String) —

    Archive link.

See Also:



138
139
140
141
142
 
# File 'lib/github_api_v3/client/contents.rb', line 138

def archive(owner, repo, format='zipball', ref='master')
  request :get, "/repos/#{owner}/#{repo}/#{format}/#{ref}", no_follow: true
rescue HTTParty::RedirectionTooDeep => e
  e.response['location']
end

#contents(owner, repo, path = '', ref = 'master') ⇒ Array, Hash

Get the contents of a file or directory.

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • path (String) (defaults to: '') —

    The path of the file or folder, defaults to the root of the repository.

  • ref (String) (defaults to: 'master') —

    The string name of the Commit/Branch/Tag, defaults to master.

Returns:

  • (Array, Hash) —

    An array of files if path is a folder, or a hash of file information if a file, symlink, or submodule is specified.

See Also:



33
34
35
 
# File 'lib/github_api_v3/client/contents.rb', line 33

def contents(owner, repo, path='', ref='master')
  get "/repos/#{owner}/#{repo}/contents/#{path}", params: { ref: ref }
end

#create_file(owner, repo, options = {}) ⇒ Hash

Create a file in a repository.

Requires authentication.

Examples:

client = GitHub.client(:login => 'caseyscarborough', :access_token => '7a329f6057f13c496ecf7fd777ceb9e79ae285')
client.create_file(
  'caseyscarborough',
  'github',
  :path      => 'lib/new_file.txt',
  :message   => 'Add lib/new_file.txt.',
  :content   => 'This is a test file.',
  :committer => { :name => 'Casey Scarborough', :email => '[email protected]' }
)

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • options (Hash) (defaults to: {}) —

    File creation parameters.

Options Hash (options):

  • :path (String) — default: required —

    The file path.

  • :message (String) — default: required —

    The commit message.

  • :content (String) — default: required —

    The new file content.

  • :branch (String) —

    The branch name, defaults to master.

  • :committer (Hash) —

    The committer’s information. If not present, the authenticated user’s information is used. It should contain the committer’s name and email, shown in the example.

Returns:

  • (Hash) —

    File content information.

See Also:



61
62
63
64
 
# File 'lib/github_api_v3/client/contents.rb', line 61

def create_file(owner, repo, options={})
  options[:content] = Base64.strict_encode64(options[:content])
  put "/repos/#{owner}/#{repo}/contents/#{options[:path]}", body: options
end

#delete_file(owner, repo, options = {}) ⇒ Hash Also known as: remove_file

Delete a file in a repository.

Requires authentication.

Examples:

client = GitHub.client(:login => 'caseyscarborough', :access_token => '7a329f6057f13c496ecf7fd777ceb9e79ae285')
client.delete_file(
  'caseyscarborough',
  'github',
  :path      => 'lib/delete_me.txt',
  :message   => 'Delete lib/delete_me.txt.',
  :sha       => '329688480d39049927147c162b9d2deaf885005f',
  :committer => { :name => 'Casey Scarborough', :email => '[email protected]' }
)

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • options (Hash) (defaults to: {}) —

    File deletion parameters.

Options Hash (options):

  • :path (String) — default: required —

    The path of the file to delete.

  • :content (String) — default: required —

    The new file content.

  • :sha (String) — default: required —

    The blob SHA of the file being deleted.

  • :branch (String) —

    The branch name, defaults to master.

  • :committer (Hash) —

    The committer’s information. If not present, the authenticated user’s information is used. It should contain the committer’s name and email, shown in the example.

Returns:

  • (Hash) —

    File content information.

See Also:



122
123
124
 
# File 'lib/github_api_v3/client/contents.rb', line 122

def delete_file(owner, repo, options={})
  delete "/repos/#{owner}/#{repo}/contents/#{options[:path]}", body: options
end

#readme(owner, repo, ref = 'master') ⇒ Hash

Get the README of a repository.

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • ref (String) (defaults to: 'master') —

    The string name of the Commit/Branch/Tag, defaults to master.

Returns:

  • (Hash) —

    README information.

See Also:



21
22
23
 
# File 'lib/github_api_v3/client/contents.rb', line 21

def readme(owner, repo, ref='master')
  get "/repos/#{owner}/#{repo}/readme", params: { ref: ref }
end

#update_file(owner, repo, options = {}) ⇒ Hash Also known as: edit_file

Update a file in a repository.

Requires authentication.

Examples:

client = GitHub.client(:login => 'caseyscarborough', :access_token => '7a329f6057f13c496ecf7fd777ceb9e79ae285')
client.update_file(
  'caseyscarborough',
  'github',
  :path      => 'lib/update_file.txt',
  :message   => 'Update lib/update_file.txt.',
  :content   => 'This is a test file.',
  :sha       => '329688480d39049927147c162b9d2deaf885005f',
  :committer => { :name => 'Casey Scarborough', :email => '[email protected]' }
)

Parameters:

  • owner (String) —

    The repository owner.

  • repo (String) —

    The repository name.

  • options (Hash) (defaults to: {}) —

    File update parameters.

Options Hash (options):

  • :path (String) — default: required —

    The file path.

  • :message (String) — default: required —

    The commit message.

  • :content (String) — default: required —

    The new file content.

  • :sha (String) — default: required —

    The blob SHA of the file being replaced.

  • :branch (String) —

    The branch name, defaults to default branch (usually master).

  • :committer (Hash) —

    The committer’s information. If not present, the authenticated user’s information is used. It should contain the committer’s name and email, shown in the example.

Returns:

  • (Hash) —

    File content information.

See Also:



92
93
94
95
 
# File 'lib/github_api_v3/client/contents.rb', line 92

def update_file(owner, repo, options={})
  options[:content] = Base64.strict_encode64(options[:content])
  put "/repos/#{owner}/#{repo}/contents/#{options[:path]}", body: options
end