Git For Authors (v0.0.10, 2025-08-08)

🛈 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[1], a story by James White[2].

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

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.

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.

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.

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.

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.

Transforming

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

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.

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

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.

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.

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.

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/[3]

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/[4]

• D. Moonfire: https://d.moonfire.us/[5]

• CC BY-SA 4.0: https://creativecommons.org/licenses/by-sa/4.0/[6]

Source

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

Metadata

Categories:

Footer

Below are various useful links within this site and to related sites (not all have been converted over to Gemini).