Creates new instance of the TadGitHub class. The construction triggers the specification/retrieval from the Drafts credentials store, of the GitHub access token.
the GitHub ID of the account to use for interacting with GitHub.
Get a set of GitHub repository data for the current account. The data is returned as an array of repository objects. This is based entirely around the GitHub API List Organization Repositories call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.
the sort order for the returned repositories. Defaults to order in which they were pushed.
number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
can be set to asc for asceding or desc for descending sort order. Default is asc.
defines which type of repositories are returned. Default is all.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(JSON.stringify(tg.TA_accountGetRepos()));
Generate an array of gist descriptions for the current account.
the sort order for the displayed gists. Defaults to order in which they were pushed.
number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountGistDescriptions().join("\n\n---\n\n"));
Retrieve information about gists for the current account. The data is returned as an array of gist objects This is based entirely around the GitHub API List gists for the authenticated user call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.
the sort order for the displayed gists. Defaults to order in which they were pushed.
number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(JSON.stringify(tg.TA_accountGistInfo()));
Given an account's gist's description, return the ID of the gist. If the description is not found, an empty string is returned.
the description of the gist to find the ID for. The description must be unique to uniquely identify a gist.
gists can be populated against the TadGitHub instance, so you can reduce API calls and time by passing false in here. Defaults to true.
the sort order for the displayed gists. Defaults to order in which they were pushed.
number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountLookupGistID("description of a gist"));
Return an array of repository names for the current account.
the sort order for the returned repository names. Defaults to order in which they were pushed.
number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
can be set to asc for asceding or desc for descending sort order. Default is asc.
defines which type of repositories are returned. Default is all.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountRepoNames().join("\n"));
Select a gist description from the gist descriptions for the current account. The function displays an HTML prompt populated with available gist descriptions. On selection, the description of the selected gist is returned. If the selection is cancelled, an empty string is returned.
the sort order for the displayed gists. Defaults to order in which they were pushed.
number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountSelectGist());
Select a gist name from the gist descriptions for the current account, and return the ID of the gist. The function displays an HTML prompt populated with available gist descriptions. On selection, the ID of the selected gist is returned. If the selection is cancelled, an empty string is returned.
the sort order for the displayed gists. Defaults to order in which they were pushed.
number of gists returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountSelectGistReturnID());
Select the name of a repository from a list of available repositories.
The user is presented with a button-based selection prompt where each button is labelled with and will cause a return of the name of
one of the available repositories for the current account. If no repository is selected, the function will return null.
the sort order for the displayed repository names. Defaults to order in which they were pushed.
number of repositories returned per page of results. Valid values are integer values between 1 and 100 inclusive. Defaults to 100.
the page number for the pages of results to return. Valid values are integers greater than 0. The default is 1.
can be set to asc for asceding or desc for descending sort order. Default is asc.
defines which type of repositories are returned. Default is all.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_accountSelectRepo());
Commit and push a new file into an existing repository's main branch.
This function can only be used for brand new files that do not currently exist in the repository at the path specified. See the
TA_repoUpdateFile() function if you wish to update an existing file. The function will return an object. If you try to update a file,
or add to a repository name that is not found, the return message attribute of the object will inform you of this as a 'missing SHA '(former) or 'not found' (latter).
A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.
the name of the repository the file is in.
the path to the file to be created, including the file name.
the content to be written to the file.
the message for the content commit.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_fileAdd("test repo", "rootfolder1/subfolder2/file3.txt", "Some words as content", "Addition of a file"));
Append content to the current content for a file in a repository's main branch.
This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified.
The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally modify
an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used
for creating new files too. The function will return an object. If you try to add to a repository name that is not found,
the object's message attribute will inform you of this as a 'not found'.
A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.
the name of the repository the file is in.
the path to the file to be created, including the file name.
the content to be appended to the end of the file.
the message for the content commit.
this optional parameter allows you to specify additional text to be placed after the existing content, but before the appended content. The default value is a newline.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_fileAppendContent("test repo", "rootfolder2/subfolder3/file4.txt", "Add this text to the end of the file", "Append demonstration"));
Get the current content for a file in a repository's main branch. The function queries the GitHub API for the specified path and content and returns a GitHubFileContent content object. This is just a convenient way to pass back two pieces of information. The success of the fetch, and the result - be it the content of the file, or the content of the error message the API provided. The function carries out the Base64 decoding of any content retrieved from the GitHub API;
the name of the repository the file is in.
the path to the file to be created, including the file name.
// Example
let tg = new TadGitHub("MyGitHubID");
let objReturn = tg.TA_fileGetContent("test repo", "rootfolder2/subfolder3/file4.txt")
if (objReturn.success) alert("SUCCESS:\n" + objReturn.content);
else alert("FAILURE: " + objReturn.content);
Return the SHA hash for a file in a specific repository's main branch.
If the file is not found, including if the repository name is not found, the function will return undefined.
the name of the repository the file is in.
the path to the file, including the file name.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_fileGetSHA("test repo", "rootfolder1/subfolder2/file3.txt"));
Prepend content to the current content for a file in a repository's main branch..
This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified.
The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally modify
an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used
for creating new files too. The function will return an object. If you try to add to a repository name that is not found,
the object's message attribute will inform you of this as a 'not found'.
A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.
the name of the repository the file is in.
the path to the file to be created, including the file name.
the message for the content commit.
this optional parameter allows you to specify additional text to be placed after the existing content, but before the appended content. The default value is a newline.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_filePrependContent("test repo", "rootfolder2/subfolder3/file4.txt", "Add this text to the start of the file", "Prepend demonstration"));
Commit and push a new file into an existing repository's main branch.
This function can be used to update existing files, and also create brand new files that do not currently exist in the repository at the path specified.
The TA_repoAddFile() function is slightly faster for creating new files as it does not first query for the SHA hash. It also will not accidentally overwrite
an existing file. But if you don't mind a fractional delay for each file, or overwriting existing files without warning, then this function can be used
for creating new files too. The function will return an object. If you try to add to a repository name that is not found,
the object's message attribute will inform you of this as a 'not found'.
A successful creation will return extensive details about the success. Please note that this function will create any new folder structures specified in the path.
the name of the repository the file is in.
the path to the file to be created, including the file name.
the content to be written to the file.
the message for the content commit.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_fileUpdate("test repo", "rootfolder2/subfolder3/file4.txt", "Some words as content", "Update of a file"));
Create a gist.
The function is capable of creating both public and private gists, and can create gists containing multiple files. The function returns the url
for accessing the gist in a web browser (html_url) when it runs successfully, and undefined should it fail.
determines if the gist is to be public (true), or private (false).
an array of file names for the files to be created in the gist. Each entry is paired with the same position entry in p_astrContent.
an array of file contents for the files to be created in the gist. Each entry is paired with the same position entry in p_astrFilename.
// Example
let tg = new TadGitHub("MyGitHubID");
app.setClipboard(tg.TA_gistCreate("New gist description", false, ["foo.txt", "bar.txt"], ["I contain foo", "I contain bar"]));
Retrieve information about a gist. The data is returned as a gist object This is based entirely around the GitHub API Get a Gist call. The API does not really document the return, but rather provides example output. We are not documenting the rather extensive output, but instead refer you back to the GitHub API documentation example on this.
the ID of the gist to be retrieved.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(JSON.stringify(tg.TA_gistFetch("abc12345")))
Retrieve file content for a gist. For each file in the gist identified by the ID, the function will populate the returned array with an entry whose content matches the content of the file. For the majority of gists this is likely be a single entry array.
the ID of the gist whose content is to be retrieved.
// Example
let tg = new TadGitHub("MyGitHubID");
alert(tg.TA_gistFetchContentToDrafts("abc12345").join("\n\n---\n\n"));
Retrieve file content for a gist into new Drafts. For each file in the gist identified by the ID, the function will create a new draft containing the content of the file. The drafts are created with the default syntax specified in Drafts. The function returns the number of drafts created, and a creation message is displayed in the app.
the ID of the gist whose file content is to be created as new drafts.
// Example
let tg = new TadGitHub("MyGitHubID");
alert("Drafts created: " + tg.TA_gistFetchContentToDrafts("abc12345"));
TadGitHub (Library)
This is a class that is used for interacting with GitHub (https://github.com).
Please note that GitHub is not designed to permit rapid successive pushes of the same file - it takes GitHub a bit of time to process all the requests it receives from the user base. When interacting with GitHub, try and batch up file updates into one push rather than say four or five all executed within a few seconds. If you try that you are more than likely to run into SHA and content mis-matches.