[0.23] GitCraft v0.9b2 -- .craft revision management using Git

[exm]

Introduction

The goal of GitCraft is to make sure that craft revisions are not lost during design and testing and to allow designers to easily restore older designs even if the craft was overwritten in the editor. In other words, GitCraft gives you the ability to undo any change to your craft provided that the version that you want to restore was saved. Thus, GitCraft can be compared to an undo button that works across launches and game sessions. GitCraft achieves this ability by integrating Git distributed revision control software with KSP.

GitCraft only affects editing your ships. It does not interact with your vessel outside of Vehicle Assembly Building or Space Plane Hangar. GitCraft integrates with the standard editor UI. In other words, your revisions are stored by git as you save them in the editor. To restore a revision you can activate the history window by clicking the git button and then click on the revision that you want to restore. GitCraft shows the part count and the game time when the ship was saved. Since version 0.9b2, attaching a part is not required to enable GitCraft, it is a "partless" plugin that works for all ships.

GitCraft is integrated with the popular Toolbar plugin (see http://forum.kerbalspaceprogram.com/threads/60066), but it will work even if the Toolbar plugin is not installed.

Currently, GitCraft works on Windows, Mac OS X, and a subset of Linux installations (i.e., x86-64 installations of Linux and corresponding 64-bit KSP executables).

We will use Aeris 4A as an example.

Clicking the Git button shows the revision history. Click save generates an entry in the history (and a git commit) as Aeris 4A is saved into the player's SPH:

I am going to change the engine to LV-909, while clicking the save button before and after (this is supposed to illustrate the process of iterative design, so bear with me here). Each time I click the save button there is a revision recorded by Git. One revision without the engine, so 38 parts there, and another with LV-909, so 39 parts again:

Now I am going to restore my Aeris 4A to its original state using Git. Just click on the third entry (the history is sorted in reverse chronological order, so later revisions appear at the top) and LVT-30 is back:

Saving at this point would generate another entry in the history as Git records that we moved the ship to an earlier point in its design. Or we could go back to LV-909 version. This pretty much covers what the plugin can do right now. If you remove the part and add it later, then the history is preserved, provided that the ship has the same name.

If nothing changed, then saving the craft triggers no commits and no new history entries appear. Except if you save right after you load. In that case KSP changes the ids of all parts for some reason, so git records a new revision.

Download

Dropbox: https://www.dropbox.com/s/luy5t5few65yuu4/GitCraft_v09b2.zip

Kerbalspaceport (updated to 0.9b2): http://kerbalspaceprogram.com/gitcraft/

Source: https://github.com/exmksp/GitCraft

Installation

1) Merge the contents of the GameData directory with the GameData directory of your Kerbal Space Program directory. Thus, the directory "Exosomatic Ontologies" should appear inside the GameData directory of your KSP. If you are upgrading from an earlier version, then the old directory in GameData should be replaced by the directory from this distribution. In other words, please delete the old directory and then put the directory from this distribution in its place.

2) On Windows, copy git2-65e9dc6.dll into root KSP directory, i.e., into the directory where the file KSP.exe is.

On Mac, copy the file libgit2-65e9dc6.dylib into the root KSP directory.

On Linux, copy the file libgit2-65e9dc6.so into the root KSP directory.

This step is necessary because GitCraft currently uses libgit2, which is a native implementaton of git. If you are upgrading from an earlier version, then this step can be skipped.

Technical Details

GitCraft initializes a new git repository in your saved game directory. Thus, if the name of your game is "default", then a git repository will be intialized in <KSP_ROOT>/saves/default/.git

To delete all data stored by GitCraft, simply remove the ".git" directory.

GitCraft automatically commits the craft file when it is saved. The part count and the timestamp are stored in the commit message.

Since version 0.9b2, the Git part is NO LONGER REQUIRED for GitCraft to work, the plugin is "partless" and is enabled for all designs. The Git part is still present in the "Control" section of the editor to provide painless upgrade path for 0.9b1 users. In the next version the part WILL BE COMPLETELY REMOVED from the plugin. The upgrade code path, which will include a dialog requesting permission to chop the part off, will be provided in the next release. Users are advised to complete all active missions that use vessels with the Git part attached to them.

Known Issues

1. If a case-insensitive filesystem is used, then GitCraft does not work well if the capitalization of the name of the ship differs from the capitalization of the filename for the file in which the ship is saved. For example, if you

are using the case-insensitive version of the Mac OS Extended filesystem (the default version), and if the name of your ship is "Rocket" and if it is saved in the file "rocket.craft", then GitCraft won't pick up the history correctly. Please make sure that capitalization of your files and the name of the ship are consistent. The issue may arise if you decide to change the capitalization of the ship's name after it was saved.

2. GitCraft does not work well with "Auto Saved Ship.craft" files generated by KSP when you launch a ship without saving its design, unless the name of your auto saved ship is "Auto Saved Ship".

3. GitCraft does not pick up history before the craft was saved or loaded. The reason for this is that plugins don't have access to the contents of the ship name widget in the editor. The plugins only have access to the ship's name, which is updated during saving or loading. To get access to the history of your ship, save it or, if it was already saved, load it.

Personal Notes

The key rationale for this plugin is to make the editor more suitable for iterative design when you try different part arrangements, evaluate them in flight and then go back to design. When I have to go more than one step back with stock editor, I need to invent a numbering strategy and stick with it, which is work, and also produces a lot of intermediate ship entries. In my case, the numbering strategy eventually leads to cleanup raids to get rid of some of the intermediate versions so that I can easily find things that I need, which is work again. So, I wrote this plugin to make it do all this work and reduce the number of intermediate designs that I actually have to save. SSTO design, for some reason, produced a lot of intermediates as I was evaluating various configurations and engine combinations.

novapunch2_03a / creativecommons by-sa 3.0

Novapunch is a collaborative mod featuring the work of several different authors. The content of the mods are copyrighted by their respective authors (which can be found in the author field in each part.cfg file) and are jointly released under the Creative Commons Attribute-Sharealike 3.0 License.

This means:

You are free:

to Share — to copy, distribute and transmit the work

to Remix — to adapt the work

to make commercial use of the work

Under the following conditions:

Attribution — You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).

Share Alike — If you alter, transform, or build upon this work, you may distribute the resulting work only under the same or similar license to this one.

With the understanding that:

Waiver — Any of the above conditions can be waived if you get permission from the copyright holder.

Public Domain — Where the work or any of its elements is in the public domain under applicable law, that status is in no way affected by the license.

Other Rights — In no way are any of the following rights affected by the license:

Your fair dealing or fair use rights, or other applicable copyright exceptions and limitations;

The author's moral rights;

Rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights.

Notice — For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.

You may see this license in its latest form (which applies to this dsitribution even if this text does not match it) at the following webpage:

http://creativecommons.org/licenses/by-sa/3.0/

When re-distributing ANY part of NovaPunch, you must include this license document and attribute credit to the authors in an approriate way. If you have any questions, you can contact the current caretaker below:

Tiberion @ KSP Forums - [email protected]

Other authors with work in this mod:

SundayPunch

NovaSilisko

Captain Slug

Tosh

Frizzank (current NovaPunch artist, including the awesome new Gemini parts)

bac9

Edited August 23, 2014 by sal_vager
0.9b2 release

[MOARdV]

This looks like a useful tool for design -- I would like to see the plugin done so it is part-free, however. I'd rather not be adding parts to my ships that are only functional in the VAB/SPH, and don't contribute to the final design. What happens if I remove the part and re-add it later (either later in the same VAB session, or in a later session)? How well does this handle ship renaming? I tend to "branch" designs off of a baseline model, do development on the branch, and then either overwrite the original, or give the branched design a new name.

[sarbian]

You should have a look at making it a partless addon. ( an example https://github.com/taraniselsu/TacExamples/tree/master/01-SimplePartlessPlugin/Source )

[MOARdV]

One other thought -- any possibility of adding a "checkin comment"? I doubt that's easy, but having something more descriptive than in-game UT and part count would help when trying to figure out which rev to unwind to. Especially if some previous revisions have parts that I have since removed from my installation (I don't want to back-rev to an invalid build, and be unable to recover the design).

[SkyHook]

Same here. Partless and this would be perfect. Excellent job, in any case!

[blizzy78]

This looks useful. As others have stated, it should be a partless plugin.

Also, it would be nice if the button could be integrated into the Toolbar Plugin.

[exm]

This is defintely possible, and, in fact, the part count and the game date is what's currently used for the comment. I wanted the plugin to be non-intrusive with the way things are in KSP, so there is no ability to specify a user comment at the moment. But I'll add this to the desired features list -- the optional ability to specify a custom comment.

[exm]

The history is preserved (the large post has it somewhere) when you re-add the part to the same ship. The part just enables the UI and auto-commit, it does nothing to git history, and will be gone in the next version. Renaming is handled as if a new ship was created, no link is stored between the old and the new in git. When you overwrite the original, the old history is preserved (the history is always preserved), so I think the plugin would work for your scenario.

[exm]

The plugin is going partless in b2, which should be released in the coming few days. Plus, I'll add the linux binary for libgit2 for the most common distro in Steam, thus covering the largest chunk, if not all, of Linux. I'll also see what it takes to integrate with the toolbar in b2, but can't promise that.

I just thought that for the first version people would expect something to happen only if a part is attached to the craft. The part is a hack of some decoupler from novapunch, you can see that I have no modeling skills.

I also had a vision of settings the attributes on git versions during the flight and after ship recovery using the science system, so that in the git it can be seen which changeset landed on the mun and so forth. The part would enable that behavior during flight, but maybe partless is the way to go there too. This feature is not going to be in b2, I want to see how much interest is in the plugin in the first place.

[Tivec]

The plugin is going partless in b2, which should be released in the coming few days. Plus, I'll add the linux binary for libgit2 for the most common distro in Steam, thus covering the largest chunk, if not all, of Linux. I'll also see what it takes to integrate with the toolbar in b2, but can't promise that.

I just thought that for the first version people would expect something to happen only if a part is attached to the craft. The part is a hack of some decoupler from novapunch, you can see that I have no modeling skills.

I also had a vision of settings the attributes on git versions during the flight and after ship recovery using the science system, so that in the git it can be seen which changeset landed on the mun and so forth. The part would enable that behavior during flight, but maybe partless is the way to go there too. This feature is not going to be in b2, I want to see how much interest is in the plugin in the first place.

I would LOVE to have the git info to what changeset did certain things. Science recovered listed per revision would be awesome - if you can add it in so that it adds up should I do several flights with the same craft that is. As for part, I second above comments that this should be part less. There is no reason to not use this sort of revision system, it is just too good Eagerly waiting for the partless version

[KvickFlygarn87]

You know what would be very neat indeed? Having the possibility to go online and edit your friends' crafts, send a "pull request" and if they like it, they could make that the main ship!

[blizzy78]

send a "pull request"

That would require an online repository, such as on GitHub. But the idea is really interesting, especially since GitHub has an API that can be hooked into.

[synik4l]

Thats was i was just thinking. I wonder if theres a way to get this setup to push files to github

[blizzy78]

Thats was i was just thinking. I wonder if theres a way to get this setup to push files to github

The repository in your save folder maintained by this plugin should be a regular Git repository, so you could always add a remote yourself and then push, even if KSP is running at the same time.

[exm]

I second what blizzy78 wrote. You could use any of the many Git tools with the GitCraft repository. For instance, you could use the console git to push the repository. It is just a git repository in the saves/<saved game name> directory, and it will work with any tool that works with git repositories. I am not planning to add the pushing functionality into the plugin, though. The plugin is supposed to make git useful during the normal game. I don't think that the use-case for pushing those repositories justifies supporting it in the plugin right now. I believe that typically pushing is not done nearly as often as craft revisions.

Edited January 19, 2014 by exm

[blizzy78]

Are you planning on adding branching support? I believe that together with the ability to enter custom commit messages, branching can be very useful in iterative design. It should come with some visual representation of the particular branches for a given craft, though. I also think that branching should be used and visualized as per-craft, while of course internally it would be per-savegame (because there is one repository per save game.)

Additionally, it should be possible to edit past commit messages, for example to add additional comments. Since the repository is only local, messing with its commit history shouldn't pose any problems.

[exm]

Interesting ideas. Regarding branching, I believe that the most common way of doing this right now is saving the ship under a different name, editing it there, and then overwriting the original ship, or simply using this other name for the new design. Question is, how much engineering do I have to do in GitCraft to make its branches more convenient than renaming approach and another question is how many users would adopt this new way of doing things, given that this is a plugin after all. I'll think more about this, but right now I am a bit skeptical about engineering GitCraft-specific branching that does not "just work" with renaming. Maybe there is a way to make renaming "just work" with git, but I don't see it right now.

Regarding the commit message, I think that the commit message should be immutable, so that people don't have ambiguities pushing and pulling things. But the craft comments can be stored in a different way, e.g., using git objects that attach messages into revisions. This is a nice feature to have, but probably 1.0-ish (after partless, which is working in the trunk of GitCraft since yesterday, and after 0.9 release, where I give upgrade path for people who have the git part in their designs).

Edited January 19, 2014 by exm

[blizzy78]

Regarding branching, I believe that the most common way of doing this right now is saving the ship under a different name, ...

Personally I don't like the "rename" way to simulate branches, let alone the fact that saving the craft overwrites previous revisions (in stock.)

I imagine a way for the plugin to show me a graph of revisions for a particular craft (its revisions and branches), and I could just select one and hit "load". I would be fine if the plugin provides a completely different way of saving and loading craft, so that I wouldn't use the regular save/load buttons anymore. It's just another way of doing things.

Regarding the commit message, I think that the commit message should be immutable, so that people don't have ambiguities pushing and pulling things.

Right, with that in mind, it is probably better to not modify previous commits.

and after 0.9 release, where I give upgrade path for people who have the git part in their designs

Not sure if that's time well spent, but of course that's your decision.

[exm]

It is time well spent because I have the git part in the history of 70% of my rockets and 100% of my SSTOs. It would suck if suddenly I cant access the history of my SCANsat launcher design because the part is gone.

[blizzy78]

ha, good point

[avivey]

Regarding the commit message, I think that the commit message should be immutable....

I'm not 100% sure if libgit2 supports it, but official git has a feature called Notes, which allows adding free-form text to commits without changing hashes. Should be right at home for this usage.

[exm]

Just a heads up, the 0.9b2 release has happened, the plugin is now partless, the first post and the thread title were updated. I kept the part inside the distribution for now, so that people have a chance to finish active missions before the part is removed in b3. In other words, the part is no longer required for normal GitCraft operation and users are strongly advised to take it off their ships. 0.9b3 release will feature an upgrade path for ships and their histories, but there is not much that I can do for active missions.

[JumpsterG]

Well envisioned, simple, and just plain awesome. This may become one of my "must-haves".

Kudos

[Kilmeister]

I will check this out... I usually end up with like at least 10 or so saves per final design because I have always been doing versions and branching manually anyways.

[tavert]

Cool idea exm. I personally manage my crafts with a naming convention (start at 1a, bump the number for a major redesign, bump the letter for minor tweaks) but the end result is my craft folders are pretty cluttered.

You should absolutely apply the versioning to quicksaves and persistence files too!