contrib/ads-gh-repo: turn into real tool

[salewski]

This issue depends on:

• issue add tool to show the authenticated user: ads-github-whoami #52 (obtain username of the authenticated GitHub user)

This issue is related to:

• issue repo-create: make repo auto-initialization optional #55 ("repo-create: make repo auto-initialization optional")

---

The functionality in the contrib/ads-gh-repo script should be used as the basis for a new ads-github-repo program, which would have the long-term goal of providing mechanisms for those portions of the GitHub "Repositories" API that manipulate a single repository.

The current functionality will create a new GitHub repo for the authenticated user, and switch it's default branch name to a specified name. Currently the specified name is just 'whatever' (hard-coded in a program variable), but a non-sketch version would honor the new (since git 2.28, spring 2020) init.defaultBranch setting from the user's git configuration, or the name specified on the command line.

UPDATE (2020-10-05 22:06:39-04:00): For now we are going to implement a stand-alone ads-github-repo-create tool, since that is the shortest path to scratching the immediate itch. However, see also issue #51 for ideas about generalizing the approach for other single-repo operations.

[salewski]

In the coming hours I'll be pushing a change that introduces the ads-github-repo-create tool. It allows you to create a new repo on GitHub from the command line, and has knobs for configuring most of the attributes associated with a GitHub repo.

$ ads-github-repo-create --help
usage: ads-github-repo-create { -h | --help }
  or:  ads-github-repo-create { -V | --version }
  or:  ads-github-repo-create [OPTION...] [--] REPO_NAME

Create a new GitHub repository.

Mandatory arguments to long options are mandatory for short options too.

  -h, --help                 Print this help message on stdout

  -V, --version              Print the version of the program on stdout

  -b, --default-branch=NAME  Specify the name to use for the default branch

  -d, --description=BLURB    Specify a short description blurb for the repo

      --force-replace        If repo already exists, attempt to replace it
                               (delete, then re-create)

      --homepage=URL         Specify a URL with more information about the reop

  -I, --disable-issues       Disable GitHub issues for the new repo

  -P, --disable-projects     Disable GitHub projects for the new repo

  -O, --output-format=WORD   Emit output in the format specified by WORD [default: text]
                               Valid values for WORD include: 'text' and 'json'

  -p, --private              Make the repository a GitHub private repo (default is public)

  -v, --verbose              Print program progress messages on stderr. Specify multiple
                               times to increase verbosity: info, debug, and tracing (set -x)

  -W, --disable-wiki         Disable GitHub wiki feature for the new repo

      --                     Signals the end of options and disables further options processing.
                               Any remaining argument(s) will be interpretted as a repo name

Report bugs to Alan D. Salewski <[email protected]>.

Default output looks like this:

$ ads-github-repo-create --default-branch 'whatev' -P -W -d 'la la la' -p -- 'aljunk-testing-repo-004'
Summary of newly created repository:

            Name: aljunk-testing-repo-004
        Is fork?: no
           Owner: salewski

    Is archived?: no
    Is disabled?: no

      Created at: 2020-10-09 05:40:07+0000
      Updated at: 2020-10-09 05:40:11+0000

     Is private?: yes
      Visibility: -

  Default branch: whatev

     Has issues?: yes
   Has projects?: yes
       Has wiki?: no

          GitHub: https://github.com/salewski/aljunk-testing-repo-004
        Homepage: -
     Description: la la la

   Clone via ssh: [email protected]:salewski/aljunk-testing-repo-004.git
 Clone via https: https://github.com/salewski/aljunk-testing-repo-004.git

Verbose (1x -- info level) output give a bit more info about what is going on behind the scenes:

$ ads-github-repo-create -v --default-branch 'whatev' -P -W -d 'la la la' -p -- 'aljunk-testing-repo-005'
ads-github-repo-create (info): GitHub repo owner is: salewski
ads-github-repo-create (info): GitHub repository does not yet exist: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): attempting to create new GitHup repo: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): successfully created new GitHup repo: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): specific default branch name specified; doing clone/rename dance
ads-github-repo-create (info): [local repo] clone newly created repo....done.
ads-github-repo-create (info): [local repo] on default branch; renaming it....done.
ads-github-repo-create (info): [local repo] pushing renamed branch to origin....done.
ads-github-repo-create (info): [local repo] track new branch from upstream....done.
ads-github-repo-create (info): [local repo] pointing HEAD to whatev....done.
ads-github-repo-create (info): remotely: attempting to PATCH dflt branch name for GitHup repo: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): successfully PATCHed existing GitHup repo: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): successfully changed default branch for existing GitHup repo: salewski/aljunk-testing-repo-005
ads-github-repo-create (info): [remote repo] delete old default branch from GitHub repo....done.
ads-github-repo-create (info): successfully changed default branch for GitHup repo: salewski/aljunk-testing-repo-005
Summary of newly created repository:

            Name: aljunk-testing-repo-005
        Is fork?: no
           Owner: salewski

    Is archived?: no
    Is disabled?: no

      Created at: 2020-10-09 05:42:33+0000
      Updated at: 2020-10-09 05:42:38+0000

     Is private?: yes
      Visibility: -

  Default branch: whatev

     Has issues?: yes
   Has projects?: yes
       Has wiki?: no

          GitHub: https://github.com/salewski/aljunk-testing-repo-005
        Homepage: -
     Description: la la la

   Clone via ssh: [email protected]:salewski/aljunk-testing-repo-005.git
 Clone via https: https://github.com/salewski/aljunk-testing-repo-005.git

[salewski]

This issue as been fixed for 'ads-github-tools-0.3.1'

The blurb about it from our 'NEWS' file:

*** issue 48: new tool: ads-github-repo-create(1)

    https://github.com/salewski/ads-github-tools/issues/48

    This new tool allows the user to create new GitHub repositories while
    working at the command line. The tool's '--help' output and sample usage
    below give a feel for what it can do:

**** ads-github-repo-create --help

     :    $ ./src/main/bash/bin/ads-github-repo-create --help
     :    usage: ads-github-repo-create { -h | --help }
     :      or:  ads-github-repo-create { -V | --version }
     :      or:  ads-github-repo-create [OPTION...] [--] REPO_NAME
     :
     :    Create a new GitHub repository.
     :
     :    Mandatory arguments to long options are mandatory for short options too.
     :
     :      -h, --help                 Print this help message on stdout
     :
     :      -V, --version              Print the version of the program on stdout
     :
     :      -b, --default-branch=NAME  Specify the name to use for the default branch
     :
     :      -d, --description=BLURB    Specify a short description blurb for the repo
     :
     :          --force-replace        If repo already exists, attempt to replace it
     :                                   (delete, then re-create)
     :
     :          --homepage=URL         Specify a URL with more information about the repo
     :
     :      -I, --disable-issues       Disable GitHub issues for the new repo
     :
     :      -P, --disable-projects     Disable GitHub projects for the new repo
     :
     :      -O, --output-format=WORD   Emit output in the format specified by WORD [default: text]
     :                                   Valid values for WORD include: 'text' and 'json'
     :
     :      -p, --private              Make the repository a GitHub private repo (default is public)
     :
     :      -v, --verbose              Print program progress messages on stderr. Specify multiple
     :                                   times to increase verbosity: info, debug, and tracing (set -x)
     :
     :      -W, --disable-wiki         Disable GitHub wiki feature for the new repo
     :
     :          --                     Signals the end of options and disables further options processing.
     :                                   Any remaining argument(s) will be interpretted as a repo name
     :
     :    Report bugs to Alan D. Salewski <[email protected]>.


**** sample usage: ads-github-repo-create

     :    $ ads-github-repo-create 'aljunk-testing-repo-006'
     :    Summary of newly created repository:
     :
     :                Name: aljunk-testing-repo-006
     :            Is fork?: no
     :               Owner: salewski
     :
     :        Is archived?: no
     :        Is disabled?: no
     :
     :          Created at: 2020-10-09 07:09:52+0000
     :          Updated at: 2020-10-09 07:09:56+0000
     :
     :         Is private?: no
     :          Visibility: -
     :
     :      Default branch: main
     :
     :         Has issues?: yes
     :       Has projects?: yes
     :           Has wiki?: yes
     :
     :              GitHub: https://github.com/salewski/aljunk-testing-repo-006
     :            Homepage: -
     :         Description: -
     :
     :       Clone via ssh: [email protected]:salewski/aljunk-testing-repo-006.git
     :     Clone via https: https://github.com/salewski/aljunk-testing-repo-006.git