Git workflow
- Learning Git — Tutorials & Tools
- Working with branches: Git Flow
- Best practices
- What to do when things go wrong
There is a broad range of resources available online for learning Git and desktop applications that make it easy to work with Git without memorizing command-line syntax.
The Pro Git book was one of the first, yet it’s been continually updated over the years and is still available to read for free.
Try Git is a playful 15-minute online tutorial that gets you up & running quickly with an illustrated step-by-step guide that shows your how to use the basic Git commands on a sample project — all in your browser window.
For more detail, Atlassian provides a series of tutorials on version control. These are particularly helpful:
- Syncing — explains how Git’s collaboration model differs from Subversion and introduces the commands used to synchronize changes between repositories and share branches with others
- Gitflow Workflow — explains how branches are used in the Git Flow branching strategy as used in the DITA-OT project
- Forking Workflow — walks through the process of sharing changes between private local repositories and the “central” codebase on GitHub.
If you’re still new to Git, or are not entirely comfortable with the command line, you may find it easier to use a desktop application to manage changes.
(All of the following are available for free for both macOS and Windows.)
GitHub Desktop is one of the simplest (and prettiest) graphical interfaces for Git. This free client by the makers of GitHub visualizes file changes and allows you to view project history, compose commits, create branches, sync changes with remote repositories and send pull requests without having to use Git on the command line.
Another highly recommended free client is SourceTree by Atlassian. It supports all of the basic Git operations like GitHub Desktop, but also provides access to more advanced Git features like interactive rebase and dialog-based support for the Git Flow branching strategy. Even many Git pros rely on SourceTree for convenient one-click access to operations that would require several steps on the command line.
Note: Recent versions require a (free) Atlassian account and lots of memory.
Billed as “a fast and friendly git client for Mac and Windows”, Fork has emerged as a viable replacement for SourceTree. Originally Mac-only, but now available for Windows too, with good Git Flow support, interactive rebasing options, and visual merge conflict resolution.
The DITA-OT project uses the Git Flow branching strategy.
In this model, change requests are tracked in feature branches that are created by branching off of the main development baseline in the develop branch. This makes it easier to keep track of related changes and merge them back into the development stream later. To find out more about how this works, see the Gitflow Workflow tutorial.
To send a pull request, create a feature branch in your fork with a name like feature/my-changes, make your changes on that branch in your fork and issue the pull request from there.
For more information, see Contributing to Open Source on GitHub.
Follow these guidelines to ensure your contribution meets our expectations and increase the chances that your changes will be included.
Before committing, run the docs Gradle build to ensure your changes build without errors.
A commit should be a wrapper for related changes, with a subject line that says what’s inside. If you fix two different bugs, create two separate commits.
Small commits make it easier for others to understand the changes and roll them back if something doesn’t work. This approach also helps to prevent conflicts, as smaller, more granular changes are less likely to cause trouble when merging your work back into the main development stream.
Git’s staging area allows you to select which files to commit — or even which lines in a file — so you can craft individual commits for each related change, even if you have made many other changes.
Committing often ensures your commits remain small and include only related changes. This also help you to share your code more frequently with others and increases the chances of your changes being approved.
If you work on epic changes in isolation and then submit a huge commit with all your changes at once, maintainers may find it difficult to understand the changes you’re proposing, and they may conflict with changes made by others in the meantime.
We care about good commit messages. As the docs document the toolkit, our commit messages serve to document our changes to the docs.
Like the subject line of an email, the first line of your commit message should concisely explain the changes in the commit so anyone reviewing code later knows what to expect.
Commit messages are a valuable form of documentation, and they’re nearly as important as the actual code we write: future engineers on your project will refer to them as part of the debugging process to try to figure out what changed, when, and why. If you didn’t do a good job in writing a commit message, you’re making life much harder for the developers on your team, including yourself.
We appreciate commit messages that stick to the following well-established conventions as outlined in the article below:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
For details on the rationale behind these conventions, see “How to Write a Git Commit Message.”
For instructions on how to recover from common errors, see Git flight rules.