GitHub and Acre Desktop - the-carlisle-group/Acre-Desktop GitHub Wiki

One of the main reasons to use Acre Desktop is that in keeping code in text files and not in the workspace, the full power of GitHub, GitHub Desktop, Git, and other widely used tools may be brought to bear on your Dyalog APL project.

GitHub provides an excellent means of sharing your APL project, managing bugs and issues, distributing it, getting feed back from users, etc.

Getting Started

You need a GitHub account - get this first. Then download and install GitHub Desktop. You will need your GitHub username and password to use GitHub Desktop.

Acre Desktop Projects and Git Repositories

When you use Git and Acre Desktop together, a Git repository and an Acre Desktop project are one and the same thing. However, a project created with Acre Desktop does not know anything about Git.

An existing Acre Desktop project can be converted (not the right word, as it is still an Acre project!) to a Git repository as follows.

In GitHub Desktop, go to File menu and select Add local repository.... Specify the existing Acre Desktop project folder as the repository path. GitHub Desktop recognizes that this folder is not (yet) a Git repository, and it asks "Would you like to create a repository here instead?" Accept this option, fill in the description and other items, and click Create Repository.

Note that you can also use the New Repository... menu item. In this case you need to take care to specify the local path as the parent folder of the existing project, and to enter the last node name of the project folder as the repository name.

Either way, the Acre Desktop Project is a now a Git repository and the Git repository is an Acre Project. We may now call the project folder an Acre repository indicating that is is both an Acre project and a Git repository. However, keep in mind that acre is SCM agnostic: it does not know whether any SCM is used to manage a project.

A Brief Introduction to Git

A good way to get an introduction to GitHub and Git is to take a familiar APL workspace, say DFNS, create an Acre test project, turn it into a repository as outlined above, and open it up simultaneously in Acre and in GitHub Desktop. Create some branches in GitHub Desktop, make some changes in the Acre project. Commit changes in GitHub Desktop. Switch branches. Explore GitHub Desktop.

Always reload the Acre project when you switch branches. When you switch branches in Git, the contents of the acre project folder (the working directory in Git jargon) is replaced with the exception of files that have been changed but not staged yet.

If your Acre project is open in the APL Session, it does not know that you have changed branches. Your current workspace will then be out of sync with what is on disk, and must be re-opened to get back in sync.

Critical issue with .gitignore

It is critical that the .gitignore file exists (and is set to ignore .acre) before the .acre folder appears in the repository. It is too late to add it after the fact.