🛈 This isn't done. Not even close. As you can see from the front page, a lot of the bullet items aren't leading to links, which I full intend to flesh out into more detailed sections. Plus I'm still in the process of dumping information and the organization isn't there. If this was the 90s, I would have a “Under Construction” GIF.

I enjoy writing as much as I like coding. While I used entirely separate tools to do either, over the years, those two processes have converge to my writing projects look like my coding projects. They use pipelines to generate the final output, source control, automated versioning, and the same suite of tools. In many cases, these tools are designed to automate tedious parts of publishing or coordinate work with others, something that can be difficult with existing tools.

The inspiration of this is Fast Trip, a story by James White.

Organization

I don't like just saying “this is how I do things” because this isn't, nor will it ever be, the One True Way™ of writing with Git. Instead, I've attempted to organize the topics from high-level ones, to global concepts, and then into advanced topics.

There is a lot of cross-linking of topics within the individual pages for relevance, but you can easily choose to ignore those links since if you follow this index page, you'll get to them in “discovery” order.

Meta Topics

• Target Audience - Who this plot is aimed for and what skills are useful to take advantage of it
• Conventions describes the notations used
• Model-View-Controller is the high-level concepts of separating the content (model) from its appearance (view)

File Formats

While the goal of this plot is to use a program—Git in this case—to manage writing, the first part is talking about “what” is being managed. In this case, it is the words you want to put into a novel or story. There are other things that you might want tracked, such as character notes, research, various pin boards and themes. These are all going to be “tracked” as part of the project.

• Text Files is a discussion of why writing should be done in plain text files
• Top Matter are the details about a given chapter or story
• Binary Files talks about why Git doesn't play well with binary files

Because of limitations in text files for doing extra formatting, I use markup to tell when to make something italic, bold, or write an epigraph.

• Markup is how to decorate a text file with some of the formatting rules that writers need
• Markdown is the most popular form of markup

Organization

Organization also becomes important with bigger projects. While you can throw everything into the project directory in a glorious mess, I have established some conventions that work well for me.

• Project Layout is how I organize my files and directories for writing projects.

Source Control

The entire reason for this plot is to use a source control program to manage writing. These programs keep a historical record as you write, allow to review changes, but also avoid accidentally overwriting changes. Programs like Git also allow you to handle feedback from editors and reviewers even when they come in over a period of time and after you've already made changes.

• Source Control discusses the systems in general and my history with them
• Git is the source control system I mainly use while writing
• Repositories are copies of the writing project
• Commits are how changes are saved to a repository (and a branch)
• Tags can be used to identify points in time where changes are made
• Branches are used to coordinate with readers and editor, or to redo chapters

Text Editors

One advantage of using text files is that almost any editor or IDE can be used to write. They have different capabilities or plugins that help.

• Visual Studio Code is a lightweight and flexible text editor

Transforming

A critical component of using text formats is how to transform them into other formats that editors and readers need.

• Transforming talks about transforming source files into the desired output
• MfGames Writing is a publishing tool for making EPUB and PDF files

Source Forges

Building on top of source control, Git in specific, are code forges which give a web view of your projects, limit others from seeing them, but also gathering feedback and edits.

• Code Forges is about online systems for managing Git repositories, pipelines, and issues
• Pipelines are automated tasks that run
• Issues are a task tracking for a project
• Pull Requests are for getting changes from others

Each forge is different from the others in almost every way. That includes setting them up, how to run the pipelines, or even how issues are tracked.

• Forgejo
• SourceHut
• GitLab
• GitHub

Versioning

One way of dealing with the “final23” files

• Versioning describes while creating a version for a story is important and how to use semantic versioning
• Conventional Commits describes a common formatting for Git commit messages to automate versioning

Other Tools

Beyond the format of the files, how a project is organized is important to keeping everything separate and also to make some of the tools more effective.

• Querying talks about using tools to work with the source files
• Markdowny is a tool used for querying the top matter

Setting Up the Environment

I've been writing novels and stories for many decades. While most of the time, I just write it and then produce the resulting PDF or EPUB, occasionally I want to go back only to find that the libraries have “bit rotted” or I based on them on a global package I forgot to migrate to my new machine or that I had modified to handle a newer book that broke the old one.

Inevitability, this means days or even weeks of bringing the project up to date just to get a PDF out of it.

Along the way, I got frustrated with that and have come up with various tools or frameworks for producing a consistent environment years or even decades later.

• Using NixOS describes setting up NixOS to make it easier to write

About This

Finally, this is a living document. Writing it as a digital plot and versioning it will hopefully allow me to evolve as we go.

• MfGames Forge
• Contributing

License

This book is distributed under a Creative Commons Attribution-ShareAlike 4.0 International license. More info can be found at https://creativecommons.org/licenses/by-sa/4.0/

The preferred attribution for this novel is:

“Git For Authors” by D. Moonfire is licensed under CC BY-SA 4.0

In the above attribution, use the following links:

• Git For Authors: https://d.moonfire.us/garden/project-layout/
• D. Moonfire: https://d.moonfire.us/
• CC BY-SA 4.0: https://creativecommons.org/licenses/by-sa/4.0/

Source

The source of this project can be found on the Moonfire Games forge. Feel free to report any issues, requests for expansion or clarifications. Alternately, you can contact me directly.