Name
GitHub::Crud - Create, Read, Update, Delete files on GitHub.
Synopsis
Create, Read, Update, Delete files on GitHub as described at:
https://developer.github.com/v3/repos/contents/#update-a-fileand also copy files, rename files and check whether files exist.
Prerequisites
sudo apt-get install curlExample
Create a file by writing some of data to it, read the file to get its contents, delete the file, then try to read the deleted file again:
use GitHub::Crud;
my $g = GitHub::Crud::new();
$g->userid = "...";
$g->repository = "test";
$g->gitFile = "test.html";
$g->personalAccessToken = "...";
say STDERR
"Write : ", dump($g->write(join '-', 1..9)),
"\nRead 1: ", dump($g->read),
"\nDelete: ", dump($g->delete),
"\nRead 2: ", dump($g->read);Produces:
Write : 'created';
Read 1: "1-2-3-4-5-6-7-8-9"
Delete: 1
Read 2: undefDescription
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Attributes
Create a new() object and then set these attributes to specify your request to GitHub
body :lvalue
The body of an issue
branch :lvalue
Branch name (you should create this branch first) or omit it for the default branch which is usually 'master'
failed :lvalue
Defined if the last request to Github failed else undef.
fileList :lvalue
Reference to an array of files produced by list
gitFile :lvalue
File name on GitHub - this name can contain '/'. This is the file to be read from, written to, copied from, checked for existence or deleted
gitFolder :lvalue
Folder name on GitHub - this name can contain '/'
logFile :lvalue
The name of a local file to which to write error messages if any errors occur.
message :lvalue
Commit message
personalAccessToken :lvalue
A personal access token with scope "public_repo" as generated on page: https://github.com/settings/tokens
readData :lvalue
Data produced by read
repository :lvalue
The name of your repository - you should create this repository first
response :lvalue
A reference to GitHub's response to the latest request
secret :lvalue
The secret for a web hook - this is created by the creator of the web hook and remembered by GitHuib
title :lvalue
The title of an issue
url :lvalue
The url for a web hook
utf8 :lvalue
Send the data as utf8 - do not use this for binary files containing images or audio, just for files containing text
userid :lvalue
Your userid on GitHub
writeData :lvalue
Data to be written by write
Methods available
new()
Create a new GitHub object.
list($)
List all the files contained in a GitHub repository or all the files below a specified folder in the repository.
Required parameters: userid, repository.
Optional parameters: gitFolder, refOrBranch, patKey.
Use the gitFolder parameter to specify the folder to start the list from, by default, the listing will start at the root folder of your repository.
If the list operation is successful, failed is set to false and fileList is set to refer to an array of the file names found.
If the list operation fails then failed is set to true and fileList is set to refer to an empty array.
Returns the list of file names found or empty list if no files were found.
1 Parameter Description
2 $gitHub GitHub objectread($$)
Read data from a file on GitHub.
Required parameters: userid, repository, gitFile = the file to read.
Optional parameters: refOrBranch, patKey.
If the read operation is successful, failed is set to false and readData is set to the data read from the file.
If the read operation fails then failed is set to true and readData is set to undef.
Returns the data read or undef if no file was found.
1 Parameter Description
2 $gitHub GitHub object
3 $noLog Whether to log errors or notwrite($$)
Write data into a GitHub file, creating the file if it is not already present.
Required parameters: userid, repository, patKey, , gitFile = the file to be written to.
Optional parameters: refOrBranch.
If the write operation is successful, failed is set to false otherwise it is set to true.
Returns updated if the write updated the file, created if the write created the file else undef if the write failed.
1 Parameter Description
2 $gitHub GitHub object
3 $data Data to be writtencopy($$)
Copy a source file from one location to another target location in your GitHub repository, overwriting the target file if it already exists.
Required parameters: userid, repository, patKey, gitFile = the file to be copied.
Optional parameters: refOrBranch.
If the write operation is successful, failed is set to false otherwise it is set to true.
Returns updated if the write updated the file, created if the write created the file else undef if the write failed.
1 Parameter Description
2 $gitHub GitHub object
3 $target The name of the file to be createdexists($)
Test whether a file exists on GitHub.
Required parameters: userid, repository, gitFile file to test.
Optional parameters: refOrBranch, patKey.
If the file exists, failed is set to false and readData is set to the data read from the file.
If the file does not exist then failed is set to true and readData is set to undef.
Returns the data in the file on success else undef if no file was found.
1 Parameter Description
2 $gitHub GitHub objectrename($$)
Rename a source file on GitHub if the target file name is not already in use.
Required parameters: userid, repository, patKey, gitFile = the file to be renamed.
Optional parameters: refOrBranch.
Returns the new name of the file renamed if the rename was successful else undef if the rename failed.
1 Parameter Description
2 $gitHub GitHub object
3 $target The new name of the filedelete($)
Delete a file from GitHub.
Required parameters: userid, repository, patKey, gitFile = the file to be deleted.
Optional parameters: refOrBranch.
If the delete operation is successful, failed is set to false otherwise it is set to true.
Returns true if the delete was successful else false.
1 Parameter Description
2 $gitHub GitHub objectlistWebHooks($)
List web hooks.
Required: userid, repository, patKey.
If the list operation is successful, failed is set to false otherwise it is set to true.
Returns true if the list operation was successful else false.
1 Parameter Description
2 $gitHub GitHub objectcreatePushWebHook($)
Create a web hook.
Required: userid, repository, url, patKey.
Optional: secret.
If the create operation is successful, failed is set to false otherwise it is set to true.
Returns true if the web hook was created successfully else false.
1 Parameter Description
2 $gitHub GitHub objectcreateIssue($)
Create an issue.
Required: userid, repository, body, title.
If the operation is successful, failed is set to false otherwise it is set to true.
Returns true if the issue was created successfully else false.
1 Parameter Description
2 $gitHub GitHub objectsavePersonalAccessToken($$)
Save the personal access token in a file.
1 Parameter Description
2 $gitHub GitHub object
3 $file Optional access file - default is /etc/GitHubCrudPersonalAccessTokenloadPersonalAccessToken($$)
Load a personal access token from a file.
1 Parameter Description
2 $gitHub GitHub object
3 $file Optional access file - default is /etc/GitHubCrudPersonalAccessTokenIndex
1 body
2 branch
3 copy
6 delete
7 exists
8 failed
9 fileList
10 gitFile
11 gitFolder
12 list
13 listWebHooks
15 logFile
16 message
17 new
19 read
20 readData
21 rename
22 repository
23 response
25 secret
26 title
27 url
28 userid
29 utf8
30 write
31 writeData
Installation
This module is written in 100% Pure Perl and, thus, it is easy to read, use, modify and install.
Standard Module::Build process for building and installing modules:
perl Build.PL
./Build
./Build test
./Build installAuthor
Copyright
Copyright (c) 2016-2017 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.