Steps for Using Quire and GitHub Together
The following steps are examples of a potential workflow when using GitHub as a project management tool alongside Quire. Creating branches and making pull requests are an optional way of working that provides extra checks and balances. You can learn more about GitHub in the Project Management for GitHub section of our documentation.
Host Your Quire Project on Github
The most common way to get started with GitHub is to upload or host your project on the platform.
- Open GitHub Desktop and click the upper left-hand corner where it says “Current Repository.” Click “Add” and choose the option to “Add Existing repository…”
- Navigate to your
[quire-project-name]folder and click “Add Repository.”
- If there are any items listed in the window’s left-hand pane, you will need to commit them to your project. As this will be your first commit, type “Initial commit” in the Summary field.
- Click the “Commit to master” button.
Download Your Quire Project from Github
If a colleague has already hosted your project on GitHub, you will need to be added as a project collaborator, and then you can download or clone the project to your computer and work on it locally.
- Open GitHub Desktop.
- Click on the upper left-hand corner of the application window, where it says “Current Repository”. Click “Add” and choose the option to “Clone repository…”
- Click the URL menu option and cut-and-paste the URL for your desired repository. (Alternately, you can copy this project directly from GitHub.com. Navigate to the project on GitHub, click the green “Code” button, select “Open with GitHub Desktop”, and follow the prompts.)
- Save the Quire project. (We recommend saying it in your home directory.)
Preview Your Quire Publication
This is recommended as a way to double-check the edits you are making in your Quire publication.
- Next, you are going to use the command line to navigate through your computer files.
- If using a Mac computer, press Command-Spacebar to open Spotlight. Then write “Terminal” and hit enter.
- For PCs, we recommend installing Git for Windows, which comes with a shell called Git BASH.
- Use the cd command to navigate to your computer’s home directory and then navigate into your
[quire-project-name]folder. (For more on using command line see our Learning Command Line article.)
- Once you are in your
[quire-project-name]folder, run the following commands:
quire install quire preview
- Go to http://localhost:1313 to view the changes live.
Open Your Project in GitHub Desktop
You will use GitHub to save, manage, and track any changes made to your Quire project.
- At the top right, click “Current Repository” and either choose your project repository from the list or add it per the instructions in Download Your Quire Project from GitHub.
Create a New Branch in GitHub Desktop
A branch is a parallel version of your project that you can edit in directly without compromising the main version.
- Before starting a new branch, click the “Fetch Origin” button at the top right. This will pull down any recently merged changes to the master project. That way when you start a new branch you are working off the most up-to-date version.
- Navigate to where it says “Current Branch” at the top of your GitHub Desktop window.
- Click the drop-down arrow and select “new branch” to the right of the Filter box.
- Name your branch.
- Select “main” where it says “Create branch based on.” This means you are creating a new branch that runs parallel to the main project.
Open Project File in Atom
When you are ready to start editing, open your Quire project in your text editor to get started. While we recommend using Atom you are welcome to use any text editor that you feel comfortable with.
- Open Atom
- Click File > Open
- Navigate to your home directory and your GitHub folder
- In Atom, expand the contents folder to see the editable markdown files
Save Changes in Atom
After you make changes in Atom, be sure to save them!
- To save, hit File > Save or Command-S (Mac) or Control-S (PC).
- If working on multiple markdown files, make sure to save each file individually. You will see a little blue dot at the top of the page if there are any unsaved changes.
Make Commits in GitHub Desktop
A commit is a record of a change or revision you have made to your Quire project. It is one step in the process of saving your changes to the git record of your project.
- At the bottom left, above where it says description, write a short name for your commit. You have the option to include a description as well.
- Press the blue button that says “Commit to [branch name].”
Push Changes in GitHub
You must “push” the changes to GitHub to save them to your repository.
- After you have made all your commits, click on the “Push Origin” button at the top right.
- Now the changes to your project have been successfully saved to your branch on GitHub.
Create a Pull Request in GitHub
Once you are done making changes, you can submit a “pull request,” a request for a collaborator to review or comment on your work.
- Click the blue-button that says “Create Pull Request.” This will take you to GitHub.com.
- Confirm that the branch in the base drop-down menu is the branch where you want to merge your changes. In most cases, this will be the master or main branch.
- You can leave the default title or type a new title and description for your pull request.
- On the right-hand side, you will see an option to choose a reviewer. Choose the colleague you would like to review your work. (Note” reviewers must be added as collaborators first.)
- Click the green-button that says “Create Pull Request” if all your changes are ready for review. Or click the drop-down arrow and choose “Create Draft Pull Request” if you are still making changes that will be included in this particular pull request.
Review and Merge a Pull Request in GitHub
Comment on and request changes to a pull request. Once the pull request is approved changes can be merged into the master copy of your project.
- Navigate to “Pull Requests” on the main page of your repository.
- In the list of pull requests, choose the one you’d like to review.
- Click “+/- Files changed”.
- Hover over the section of text you would like to comment on.
- You will see a blue square with a plus mark pop-up. Write your comments here.
- When you are done commenting click, “Start a Review.” You will have the option to comment, approve, and request changes.
- Once the pull request has been approved, provided there are no conflicts, you will see a green-button that says “merge pull request.” Click this and, voila, your changes are now incorporated.