Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.
Resources
Rules
Git Logo by Jason Long is licensed under the Creative Commons Attribution 3.0 Unported License.
Unless you need a "stable" version of your in-development work I wouldn't split parts of it into branches.
Use branches to draft and explore changes, and merge them when they're accepted into the baseline draft/current state.
Don't be afraid to merge "better than before but not final or complete or conclusive" work. You're trying to evolve, not construct final parts to combine. They won't ever be final.
This is great advice. I don't believe we need a "stable" version. I mean, at a certain point our work will be ready and that's it. We are not going to have different releases. We will have other formats (like a shorter version of this report), but in that case those would live as a different repository I guess
Sounds like a fine usecase for git.
I don't know the structure of your work, and there is not one correct way to do things.
"Too short" branches would be when you open and merge into main multiple times a day. "Too long" branches would be when one person works on their own branch for months without checking the whole.
In software, before merging into main, it's customary to have a person other than the author review and (dis)approve the changes.
Thank you for your reply! What are the "objects" possibly determining a branch? Features? Chapters? Writers? Releases?
The first commit on main would be a rough structure of the document.
Then branches for each feature (in your case perhaps "abstract", "chapter 2: intro" "chapter 2: methodology" "chapter 2: conclusion"), and branches for bugs (in your case perhaps: "proofreading and errata chapter 2", "correct legend figure 4.2").
I would go with a trunk based approach. In other words no other long lived branches other than main. Push for review often and merge to main as soon as it's approved.
If you don't see a need for a more complex branch strategy, you probably don't need it. Branches are always an increased risk for conflicts and can be a pain to resolve.
Yeah, I agree. I mean, we have different files for different chapters. So I guess a trunk based approach would work. Benefits from using a branch for each chapter variations might be needed, but only in specific cases. And to be honest, I think this does not really applies to us
I think this will heavily be influenced by how you distribute your work. Does everyone works on everything (branch by chapters) or is your report clearly divided to every author (then maybe branch by author to make it easier)? In addition every author can decide to branch down further if they feel the need to do so.
To be honest, in the beginning, I started with a branch for my own version of some chapters. We thought it was ok and merged into main. Maybe if we are going to use branches at all, having a branch for each author could make sense. We need to discuss this
I have no idea but I suposse it would need some agreement on the index/barebones before anything else.
We opted for each file as a chapter. We already have the general structure. We are wondering what is the best approach. Maybe we should not have branches at all(?)
For us to be able to help you, I think you need to give us some more details about the organization of your work. If each chapter is a separate text file, then you don't really need to do any branching at all (assuming people will only make changes on their own files and not touch others' work). If it is a single text file, branching (or anything else, to be honest) will not help much.
I assume chapters will have their separate files. As long as you can control who touches which file, everybody can work on the same branch (also referred to as "trunk based"). But if you fear that people may interfere with each other's work (willingly or by accident), then it makes sense to create a branch per chapter to keep contributors at a distance from each other. But working on a single repository requires some sort of an agreement on the workflow.
I totally agree. We have a file for each chapter. We might just keep a trunk based approach mainly, and resort to short lived branches to allow writers to get their contributions reviewed.
Thank you for the advice
If you have long-lived branches, I would do as you say: treat each branch like its own release, then merge once it's ready. Make sure that everyone knows that those branches exist and that they must not create new ones. You could create all the branches at once with specific names so that no one is confused (like 01-chapter_something, 02-...)
Not sure if this advice really applies, given i haven't used Git for any reports myself and I don't know how you are doing the text based project. I did pretty much all my uni reports in a online latex document site which allowed shared editing, so there was some history but all edits were live to the main doc.
But with the power of latex at least, you can have the main file do import and usages, and maybe some setup. And then combine other files representing anything you want. Such as one for front page, one per chapter or one for appendixes.
Then just can do changes/new sections in feature style branches, and it's up to you if you want things to go to the main branch, or have a dev like branch where further refinement can happen if your work is structured and not all over the place like my report writing was.