<commit_before># Simply Github

A simple tool for working with Github remotely. The basic interface is minimal.
With ``Simply Github``, you can:

    * Create and delete branches.
    * Add or remove files from a branch.
    * Merge branches.


## Profiles

Pretty much every ``Simply Github`` function needs a profile as its first
argument. A profile provides ``Simply Github`` with two pieces of information.
It tells ``Simply Github``:

    * The ``repo`` it should connect to.
    * The ``token`` it should connect with.

The ``repo`` should be in the standard git form of ``:owner/:repo``, e.g.,
``jtpaasch/simplygithub``. The ``token`` should be a valid personal access
token, which you can create from your Github account, under account settings.

To generate a profile to use just during a coding session, import the
``simplygithub.authentication.profile`` package and use the
``ephemeral_profile()`` function. For example::

    from simplygithub.authentication import profile

    my_profile = profile.ephemeral_profile(repo="jtpaasch/simplygithub",
                                           token="<KEY>...")

You can then use ``my_profile`` for any of the ``Simply Github`` functions
that need a profile.

An ephemeral profile only lasts for the coding session though. It disappears
when the ``my_profile`` variable disappears. If you want to store a profile
in a config file, use the ``write_profile()`` function.

That function takes the aforementioned ``repo`` and ``token`` arguments, but
you also need to give the profile a name so you can retrieve it later.

This creates the same profile as above, but names it ``default``::

    from simplygithub.authentication import profile

    my_profile = profile.write_profile(name="default",
                                       repo="jtpaasch/simplygithub",
                                       token="<KEY>...")

That will save the profile in a file at ``~/.profile/simplygithub/github``.
(You can also create/modify this file yourself, by hand.)

You can load the profile anytime later with the ``read_profile()`` function::

    from simplygithub.authentication import profile

    my_profile = profile.read_profile("default")

Once you have a profile loaded into a variable (like ``my_profile``), you can
use it in any other ``Simply Github`` function that requires a profile as its
first argument.


## Creating branches

Use the ``simplygithub.branches`` package to work with branches::

    from simplygithub import branches

To see a list of all your branches (using ``my_profile`` from above)::

    branches.list_branches(my_profile)

To create a branch off of master::

    branches.create_branch(my_profile, "feature-branch", branch_off="master")

To get the SHA the branch's HEAD points to::

    branches.get_branch_sha(my_profile, "feature-branch")

To merge a feature branch into master::

    branches.merge(my_profile, "feature-branch", merge_into="master")
    
To delete a branch::

    branches.delete_branch(my_profile, "feature-branch")


## Adding and removing files from a branch

Use the ``simplygithub.files`` package to work with files::

    from simplygithub import files<commit_msg>Fixed section headings on readme.<commit_after>Simply Github
=============

A simple tool for working with Github remotely. The basic interface is minimal.
With ``Simply Github``, you can:

    * Create and delete branches.
    * Add or remove files from a branch.
    * Merge branches.


Profiles
--------

Pretty much every ``Simply Github`` function needs a profile as its first
argument. A profile provides ``Simply Github`` with two pieces of information.
It tells ``Simply Github``:

    * The ``repo`` it should connect to.
    * The ``token`` it should connect with.

The ``repo`` should be in the standard git form of ``:owner/:repo``, e.g.,
``jtpaasch/simplygithub``. The ``token`` should be a valid personal access
token, which you can create from your Github account, under account settings.

To generate a profile to use just during a coding session, import the
``simplygithub.authentication.profile`` package and use the
``ephemeral_profile()`` function. For example::

    from simplygithub.authentication import profile

    my_profile = profile.ephemeral_profile(repo="jtpaasch/simplygithub",
                                           token="a3<PASSWORD>...")

You can then use ``my_profile`` for any of the ``Simply Github`` functions
that need a profile.

An ephemeral profile only lasts for the coding session though. It disappears
when the ``my_profile`` variable disappears. If you want to store a profile
in a config file, use the ``write_profile()`` function.

That function takes the aforementioned ``repo`` and ``token`` arguments, but
you also need to give the profile a name so you can retrieve it later.

This creates the same profile as above, but names it ``default``::

    from simplygithub.authentication import profile

    my_profile = profile.write_profile(name="default",
                                       repo="jtpaasch/simplygithub",
                                       token="a<PASSWORD>...")

That will save the profile in a file at ``~/.profile/simplygithub/github``.
(You can also create/modify this file yourself, by hand.)

You can load the profile anytime later with the ``read_profile()`` function::

    from simplygithub.authentication import profile

    my_profile = profile.read_profile("default")

Once you have a profile loaded into a variable (like ``my_profile``), you can
use it in any other ``Simply Github`` function that requires a profile as its
first argument.


Creating branches
-----------------

Use the ``simplygithub.branches`` package to work with branches::

    from simplygithub import branches

To see a list of all your branches (using ``my_profile`` from above)::

    branches.list_branches(my_profile)

To create a branch off of master::

    branches.create_branch(my_profile, "feature-branch", branch_off="master")

To get the SHA the branch's HEAD points to::

    branches.get_branch_sha(my_profile, "feature-branch")

To merge a feature branch into master::

    branches.merge(my_profile, "feature-branch", merge_into="master")
    
To delete a branch::

    branches.delete_branch(my_profile, "feature-branch")


Adding and removing files from a branch
---------------------------------------

Use the ``simplygithub.files`` package to work with files::

    from simplygithub import files
{'fraction_non_alphanumeric': 0.09979885502088813, 'fraction_numerical': 0.00015472690700912888, 'mean_word_length': 3.5329593267882187, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4568254', 'n_tokens_mistral': 1734, 'n_tokens_neox': 1668, 'n_words': 754}