====== Github Desktop ======

Github released a neat GUI for managing local repositories with ''git'' called [[https://desktop.github.com/|Github Desktop]]. It's experimental but in a pretty functional state if you choose to use it, it can be a great learning tool if you're new to contributing to open-source code. With that being said, if you want to do more advanced or technical stuff, you'll probably want to switch over to using the ''git'' command line tool in the future as it offers much more functionality.

{{:github-desktop-screenshot-windows.png?nolink&720|A handy UI to accompany usage of Git. This is only useful for Github-hosted repositories.}}

<WRAP center round info>
Github Desktop is only confirmed to be working for Github-hosted repositories, which is what Batocera uses. This may not work as equally for other repositories hosted on other services.
</WRAP>

===== How to install =====

==== Windows ====

Easy, just go to [[https://desktop.github.com/|Github Desktop's download page]] and follow their instructions.

{{:github_desktop_website.png?nolink&640|}}

=== Note for Windows users ===

Windows users should take some extra precautions when editing Linux-spawned files. NTFS, the default filesystem for Windows, does not support many features that the more modern filesystems Linux supports such as symlinks, file attributes (including the extremely important executable bit), etc. By default, Git will do its best to transparently convert file attributes to and from Windows-acceptable formats to the ones on the remote repository, but edits are not always possible (such as with two symlinked files).

Windows' built-in text editing software doesn't support the line terminators used in Linux text files. Install a good text-editing software such as [[http://notepad-plus-plus.org/|Notepad++]] to work around this; make sure to set the correct line terminators in **Settings** -> **Preferences...** -> **New Document** -> **Format (Line ending)** to "Unix (LF)":

{{:notepadplusplus-eol-setting.png?direct&600|Screenshot showing the preferences window, "New Document" category, with "Format (Line ending)" set to "Unix (LF)".}}

Then also tell `git` to not automatically convert LF to CRLF by adding the following to your ''C:\Users\<your-name>\.gitconfig'' file:

<code>
[core]
	autocrlf = input
</code>

You can enable experimental symlink support within Windows by installing the [[https://schinagl.priv.at/nt/hardlinkshellext/linkshellextension.html|Link Shell Extension]] (it is strongly recommended to read through that entire page to be aware of its shortcomings and Windows' general disdain towards symlinks) and adding the following to your ''C:\Users\<your-name>\.gitconfig'' file:

<code>
[core]
	symlinks = true
</code>

<WRAP center round info>
If you already have a repository setup and are simply transitioning over to Github Desktop, you'll also need to erase the ''symlinks = false'' from the ''<repository-name>/.git/config'' file in the repository folder itself.
</WRAP>

Once this is done, change Github Desktop's shortcut to always launch in administrator mode, as that will allow it to create and edit symlinks.

==== Mac ====

Easy:
  - Go to [[https://desktop.github.com/|Github Desktop's download page]]
  - Click "Download for macOS" and extract the downloaded ZIP archive
  - Double-click ''GitHub Desktop'' from the extracted files
  - Follow the on-screen instructions

==== Linux-based distributions ====

Github Desktop does not official support any Linux-based distributions, but a community fork has been released at [[https://github.com/shiftkey/desktop|Shiftkey's Github Desktop repository]]. The readme contains the most up-to-date installation instructions for most major distributions.

In the case that you are using a distribution that cannot install ''deb'' or ''rpm'' packages, an AppImage is available on [[https://github.com/shiftkey/desktop/releases|the releases page]].

<WRAP center round info>
On that note, since Github Desktop uses Electron, it doesn't have that many dependencies. It may just be possible to simply copy + paste the package's contents from the ''rpm'' package into a random folder and just execute it from there.
</WRAP>

<WRAP center round tip>
On Solus, using the AppImage is recommended. Download it and mark it as executable. Installing Chrome (from the third party section in the software updater) is required to authenticate the sign-in. <wrap lo>You don't actually need to use Chrome itself to do the authentication, it just needs to be installed. Yeah.</wrap>
</WRAP>

===== Setting up Github Desktop =====

==== Sign in ====

After launching Github Desktop for the first time, you should sign into your Github account. In case the dialogue didn't automatically appear, you can do this by going to **File** -> **Options** -> **Accounts** and clicking **Sign in** in the "Github.com" section.

Once signed in, it should look like this:

{{:github-desktop-signed-in.png?direct&500|}}

<WRAP center round help>
If having difficulty getting your browser to recognize the protocol (either due to weird permission issues or manual installation), reboot your computer and try again. Seriously. Github Desktop installs the protocol handlers which only get activated on boot for some operating systems.

If it's still failing after that, it is possible to copy and paste a known-working configuration folder from another operating system into the one you are having the difficulties with.

  * Windows config folder: ''Users\<Your username>\AppData\Roaming\GitHub Desktop''
  * Linux config folder: ''~/.config/GitHub Desktop''

Make sure GitHub Desktop is closed before doing this.
</WRAP>

==== Fixing submodule downloading ====

Batocera makes ludicrous use of submodules to compile. You'll find that when attempting to make new branches, they'll default to an older version of the submodule than the one that's currently being used. To work around this, add the following lines to your global gitconfig (on Windows, this is at ''C:\Users\<your name>\.gitconfig''; on Linux, this is at ''~/.gitconfig''):

<code>
[submodule]
	recurse = true
</code>

<WRAP center round tip>
This can also be achieved by running ''%%git config --global submodule.recurse true%%'' from the currently installed instance of ''git''.

In a typical Windows installation of Github Desktop, this is at ''%%C:\Users\<your name>\AppData\Local\GitHubDesktop\app-<#.#.#>\resources\app\git\cmd\git.exe%%''. Navigate to that folder, then press ''[Shift]'' + right-click and press **Open command window here**, then run ''%%git config --global submodule.recurse true%%''.
</WRAP>

==== Clone the repository ====

Go to **File** -> **Clone repository...**. This will open up a dialogue window:

{{:github-desktop-clone-repo.png?nolink&400|}}

If you've already forked the project, great! Just click it here and clone it, choosing to contribute to the parent project.

Otherwise, click on **URL** at the top to switch to another screen.

Enter the URL of the repository you want to clone. Here, I will be copying the [[https://github.com/batocera-linux/batocera-bezel|batocera-bezels]] repository, but the process is identical for [[https://github.com/batocera-linux/batocera.linux|batocera.linux]] as well. This is what it should look like:

{{:github-desktop-clone-new-repository.png?direct&400|}}

Select your desired folder and click **Clone**. Please wait patiently while the repository is downloaded to your computer.

{{:github-desktop-cloning.png?direct&400|}}

When asked what project you'd like to contribute to, select the one hosted by batocera.linux, not recalbox or your own account.

==== Create a new branch ====

Nice! Now we have the repository on our computer. The default branch is ''master''. In order to make our changes, we must first create a new branch. Click on the **Current branch** at the top, then click **New branch**:

{{:github-desktop-new-branch.png?direct&500|}}

It's useful to give the branch a meaningful, one-or-two word name. I'm intending on making edits to the readme file, so I'm going to name my branch ''readme''.

<WRAP center round tip>
Note that branch names are limited to alphanumeric, hyphen and underscore characters, and no two branches can have the same name; Github Desktop will inform you of this and make the appropriate changes as needed.
</WRAP>

Now this branch is stored locally on the computer, but it doesn't exist on the online remote repository. To fix that, click **Publish branch** in the main section:

{{:github-desktop-publish-branch.png?direct&500|}}

But you'll notice that this will partially fail as you don't have write access to the Batocera-owned repository! You'll be offerred to create your own fork of the repository to make your edits to, click **Fork this repository**:

{{:github-desktop-fork.png?direct|}}

<WRAP center round info>
If you're cloning an already forked project, this step will not occur.
</WRAP>

You'll then be asked how you'd like to use the project. Leave it on **To contribute to the parent project** pointed at batocera.linux and click **Continue**:

{{:github-desktop-how-to-use-project.png?direct&400|}}

You'll be taken back to the main page. Click **Publish branch** again, and this time everything will be successful!

{{:github-desktop-fork-successful.png?direct&720|Notice that the icon in the top left has changed from a repository book to a fork tree.}}

Your files are now ready to be edited.

==== Editing files ====

Click on **Show in Explorer** (or the name of your preferred file manager if you have something different from default) to open up a folder directly to your repository and start editing away! You have some guidelines on [[:batocera.linux_buildroot_modifications|this page to compile individual packages]], a [[:notable_files|list of notable files and their location on a live install]] and [[:compile_batocera.linux|this page for more general compilation of the whole Batocera Linux system]].

==== Committing changes ====

You'll notice that as you edit files, the files you edit and changes you've made will appear in Github Desktop:

{{:github-desktop-changes-before-commit.png?direct&720|}}

You can make as many edits as you'd like. Once you are ready to commit your changes to the fork, fill out the details of the changes you've made in the description box at the bottom left of the screen and click **Commit to <branch-name>**.

{{:github-desktop-commit-description.png?nolink|}}

The commit is now saved locally to your repository, but has yet to be pushed to your remote fork. Click on **Push origin** to do so:

{{:github-desktop-push-origin.png?nolink&720|}}

==== Make a pull request ====

Once your changes are committed, click on **Create Pull Request** to open your web browser to make a pull request on Github itself.

{{:github-desktop-pull-request.png?nolink&500|}}

<WRAP center round tip>
New feature: Pull request changes can be previewed in Github Desktop before going to the web page to preview it. This can be useful, but it's not needed right now. Click the down arrow next to the **Preview Pull Request** to switch it back to **Create Pull Request**.
</WRAP>

Github is smart enough to automatically insert the title and description you entered for the commit you made earlier, but do note that this is only for the first commit you made. If you've made multiple commits, make sure to double check the fields here.

It is recommended to switch this to a **Draft Pull Request** until you've become more familiar with the process. This will allow you to make mistakes without worry until you click **Ready for review**. First click the down arrow and select **Create draft pull request**:

{{:github-make-draft-pull-request.png?nolink&600|}}

You'll notice that the button now says "Draft pull request". Click it to continue:

{{:github-draft-pull-request.png?nolink|}}

Yay!

{{:github-draft-pull-request-ready.png?direct&600|}}

<WRAP center round info>
A pull request can only be done via the web page, there is no way to do this from Github Desktop itself. This is by design.
</WRAP>

When you're ready to submit your changes, click **Ready for review**.

==== I messed up and need to change something ====

Don't fret, you can still make changes to your pull request //as long as it hasn't been merged yet// (a draft pull request indicates it is not ready to be merged yet). Ensure that you're on the branch that you made the pull request from, make your additional changes, and commit them again. The changes will be reflected in the pull request immediately.

If you've ended up making many commits, it is polite to "squash" them into one commit as it is easier to keep track of things that way. After all, if you're a dev and find that a component of Batocera has broken due to a change made months ago, sifting through ten or twenty commits titled "fixed mistake" in the commit history with little context as to what they were for isn't the most pleasant experience.

To squash multiple commits into one:
  - Ensure you're still on the branch you have made the pull request on
  - Click on **History** near the top left of the window
  - Select the commits you wish to squash (either by holding ''[Ctrl]'' and clicking each one or holding ''[Shift]'' and selecting the first commit you made)
  - Right-click and select **Squash <#> commits** {{:github-desktop-squash-commits.png?direct|}}
  - Create a new title and description that includes all your changes\\ {{:github-desktop-squash-description.png?nolink|}} {{:github-desktop-squash-successful.png?direct&1000|}}
  - Click **Force push origin**\\ {{:github-desktop-force-push-origin.png?direct&720|}}
  - Confirm the changes have been reflected in the pull request\\ {{:github-force-push-confirmation.png?direct&720|}} {{:github-check-force-push.png?direct&900|}}

==== Fetch upstream changes ====

In order to keep your local master branch in sync with changes made to the upstream master branch, you'll have to fetch the changes. Normally, you would just click **Fetch origin** at the top to do so, but if you do that you'll notice something after a while. On your Github Desktop, it will claim that there are no changes:

{{:github-desktop-no-local-changes.png?direct&600|}}

But if you visit the fork on your Github webpage:

{{:out_of_date_on_github.png?direct|}}

To repair this, there are multiple methods:

=== Just use batocera.linux's master branch from upstream ===

This is the simplest solution, just use batocera.linux's ''upstream/master'' branch instead. However, if you attempt to do this, you'll be met with a "Fatal: this branch already exists" error. This is because your fork's master branch has the same name. This can be worked around by either:

  * Renaming the ''master'' branch to something unique; or
  * Deleting the ''master'' branch locally from your computer

To do the latter, first be on a branch that isn't master, then right-click the local ''master'' branch (it shouldn't have anything ahead of it like ''upstream/'' or ''origin/'') and choose to delete it. If you are offered to delete the branch on the remote as well, decline (what's on the remote doesn't truly matter for our purposes here). You'll then be able to switch to ''upstream/master'' with no issues.

=== Merging/rebasing the master branch ===

Similar to the command line procedure, we will merge directly from upstream. If you choose to use this method, this needs to be done every time you want to sync with upstream.

== Using Github Desktop ==

Merge the upstream/master branch to your own master branch clicking **Current branch** -> select the "master" branch of your fork -> **Current branch** (again) -> **Choose a branch to merge into master**. That will bring the merge window up. Choose "upstream/master" from the list and **Create a merge commit** (or if you want a "cleaner" commit history, **Rebase**):

{{:github-desktop-merge-upstream-master.png?direct&400|}}

Then push your changes to your remote fork by pushing the commits. This will be your "fetch" method.

== Using Github webpages ==

Navigate to ''%%https://github.com/<your name>/batocera.linux%%'', select **Fetch upstream** -> **Fetch and merge**:

{{:github-fetch-and-merge-upstream.png?direct&600|}}

You will need to [[#fetch_the_changes|fetch the changes]] from Github Desktop after doing this.

== Confirm fork has been updated ==

You can check that the remote is up to date by checking your fork online at Github:

{{:up_to_date_github.png?nolink&800|}}

=== Redirecting the local master branch header ===

Instead, you can edit the branch settings for your ''master'' branch to instead fetch from upstream instead of your fork (origin). This only needs to be done once.

Change the currently tracked upstream branch by running the command ''%%git branch --set-upstream-to=upstream/master%%''.

On Windows: 
  - Open ''C:\Users\<your name>\AppData\Local\GitHubDesktop\app-<#.#.#>\resources\app\git\cmd\''
  - Press ''[Shift]'' + right-click and click **Open command window here**
  - Run ''%%git -C "C:\<path\to\repository>" checkout master%%''
  - Then run ''%%git -C "C:\<path\to\repository>" branch --set-upstream-to=upstream/master%%''

<WRAP center round info>
If you use this method, your fork online will not be updated in sync with your local branch. This does not matter, as all your new branches will be based on upstream/master, so any changes will just not be reflected on your online fork. You can always [[#using_github_webpages|update using Github webpages]] to keep the online repository up to date as well.
</WRAP>

=== Fetch the changes ===

After updating the fork online or editing the branch settings, simply click **Pull upstream**/**Pull origin** at the top of the window:

{{:github-desktop-pull-upstream.png?direct&720|}}

==== Making new changes ====

Now that you've got everything set up making new changes in the future is much simpler:
  - [[#fetch_the_changes|Fetch the latest changes made upstream]]
  - [[#create_a_new_branch|Make a new branch]]
  - [[#editing_files|Make your edits to the files]]
  - [[#committing_changes|Commit those changes to your fork]]
  - [[#make_a_pull_request|Make a pull request]]

===== Troubleshooting =====

Github Desktop is still in an experimental state and sometimes issues with usage crop up. [[https://docs.github.com/en/desktop|Their documentation]] should answer most basic questions.

==== I can't sign in/authentication fails/can't push commits to my remote ====

Try resetting your username and authentication token by going to **File** -> **Options** -> **Accounts** -> **Sign Out**, then signing in again. You may also need to explicitly sign out of Github on your web browser to get it to regenerate a new, valid token.

==== Other/more complicated issues ====

Refer to [[https://github.com/shiftkey/desktop/blob/linux/docs/known-issues.md#linux|Shiftkey's Known Issues page]] to see if there's a known workaround. There is also a similar page on [[https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/overview/supported-operating-systems|Github Desktop's official documentation]]. Unfortunately Batocera itself cannot offer much support for using Github Desktop; if you're having too many issues with Github Desktop it's suggested to [[:contributing-to-batocera|switch over to using the Git command line tool]] instead.