Has anyone migrated to the Git integration?

[doc_guy]

The company I'm working for uses SmartGit and ignores the GIT integration with Flare. It seems to work surprisingly well. We aren't able to connect to our GIT repository from Flare because our repository is protected by SSH.

I was a bit leery at first, thinking it would be better to have Flare connected, but SmartGit works really well, and is very fast, considering we have more than a thousand topics in the system. I recommend it.

[Rona Kwestel]

Tova, if I'm understanding your question correctly, it sounds like you're thinking of doing something like this: create conditions for changes pertaining to a given (JIRA) ticket, say, then create a target for a given release/build version, which includes all the tickets that apply to that release. I think there are two issues with this method that I can see:

1. This will start to become very unwieldy once a lot of tickets/changes have been added to the content. For each subsequent release, you now need to include all the tickets from the previous releases, and you need to exclude any tickets that aren't ready for release yet.

2. Some changes have cascading effects that would be almost impossible to conditionalize, such as changing the name of a file or changing the stylesheet or other project-wide content.

We're using git outside of Flare (the integrated interface didn't work for us at all), and so far our branching and re-merging has been minimal, so I can't confirm that it will always work perfectly every time, but even with our non-Flare html help, there are some kinds of changes that are hard to merge without manual intervention, such as tables.

[ChoccieMuffin]

It seems that integrated version control is a pain whatever version control system you use, so would it be possible for you to use version control OUTSIDE of Flare?

[LeslieT]

Started reading new posts and went back to realize that I am the one who started this thread -- LOL!

Anyway, I finally came to the realization that there was just no real reason to use the Flare-Git integration. Using SourceTree as our Git client works great and Flare just doesn't need to be involved. The only thing I have to be careful about is to close Flare before I switch branches (it hates to have a project open when you do that because you are changing them outside of Flare while it has them loaded).

[MattyQ]

I finally came to the realization that there was just no real reason to use the Flare-Git integration. Using SourceTree as our Git client works great and Flare just doesn't need to be involved. The only thing I have to be careful about is to close Flare before I switch branches (it hates to have a project open when you do that because you are changing them outside of Flare while it has them loaded).

I second this. We use SourceTree, also, and managing the Flare project without the integration has been painless.

[doc_guy]

I tried binding my Flare project to Git, only to discover that since Flare doesn't support ssh connections to the remote repository.

FYI, this is a new feature of Flare 12 - SSH support for GIT. You may try to see if it works.

[Rona Kwestel]

Thanks, Paul. For now, I think we're fine with just using Git directly outside of Flare. I don't really see any advantage to the integration. As soon as you make changes to any files, Git recognizes which files are changed, and you can then commit them to the branch, and ultimately merge them back into the master branch when a full set of changes is ready to go. We then only publish from the master branch.

So far, it seems to be working well, though admittedly, I'm currently the only writer on our Flare project. Once we move more content over to Flare, my co-writer will also be in the mix, but I don't anticipate any issues that we don't already have, where some merges are trickier than others if common content has been changed by both us in different branches for different tickets.

So, when is Flare 12 coming out?

[RamonS]

So, when is Flare 12 coming out?

Yesterday!

[doc_guy]

Thanks, Paul. For now, I think we're fine with just using Git directly outside of Flare. I don't really see any advantage to the integration.

Honestly, now that I've tried it, I'm going to be sticking with Smart GIT anyway. Like you, I don't see any benefit to using the GIT integration instead of Smart GIT.

If we were talking SVN, then that is a whole different story. I'd definitely recommend the integration in that case. But in the case of GIT, I don't see any value add to using Flare to do the source control work.

[Rona Kwestel]

So, when is Flare 12 coming out?

Yesterday!

I love it when the future is already here.

[SteveS]

So, when is Flare 12 coming out?

Yesterday!

I love it when the future is already here.

As my grandmother was wont to say:

Today is the tomorrow you worried about yesterday...

[AnthonyD]

So, with Flare 12 out for a week or so now. Has anyone seen an improvement in functionality or a resolution to some of the problems mentioned in this thread?

I've been asked to take another look at a more robust source control method than copying the whole project file after a document release and archiving the copy in another directory.

It doesn't appear that there was much progress with 11.1 over the last few months.

[Rona Kwestel]

AnthonyD, I love your tag line.

I don't have an answer about Git-related updates in Flare 12, but just wanted to restate that it sounds like many, including us, are using Git outside of the Flare UI, and it seems to work just fine. In other words, once you're in your branch, you simply edit files as needed in Flare and let Git keep track of the changes. When you're done, you use Git to merge your changes back into the master branch. Flare doesn't need to know anything about it.

[AnthonyD]

Hi Rona,

Thanks, its pretty accurate.

I myself don't have a lot of experience with Git, so can you outline how you are using it without binding it to flare?

[Rona Kwestel]

I have to tell you that Git has a bit of a steep learning curve, which might be slightly alleviated if you use one of the graphical interfaces like Git Extensions, but once you get used to it, it's kind of nice. We use Cygwin for the command line interface to git.

I'm no Git expert at all, and we're fortunate to have a couple of guys on our development team who are, which helps a lot, but here is how we're using Git with Flare in a nutshell.

You create your Git repository on a server somewhere on your network with whatever state of your Flare project you want to start with initially. This will be your "master" branch, which is your baseline. Our project folder looks like this:

FlareProjectFolder.png

You'll want to tell Git to ignore generated content like the Output and Analyzer folders in the .gitignore file, so that changes to those folders are not seen as changes to your source every time you build or analyze your project. The .git folder is where Git keeps track of your branches and all the incremental changes, so you don't want to mess with that folder at all unless you really know what you're doing.

As a rule, you should never work directly in the master branch, so whenever you want to make changes to the project, you should create a separate branch, make the changes there, and then merge them back into the master branch when you're done. We use JIRA to keep track of updates to our software and associated doc content, so when we need to update our content, we create a branch off of the master and name it accordingly in the form of <JIRA ticket number>_<feature-description>.

Git effectively makes an exact copy of the master branch, giving you a separate "sandbox" in which to make your changes, but you don't get new folders on your hard drive - you're always working on the same project folder, but Git is simply applying the diffs stored in that .git folder for whichever branch you're on. It's a good idea to not have project files open when you create a branch just to make sure that when you switch into that new branch, there aren't unsaved files that couldn't be overwritten with the latest version from the master.

Once you're in your branch, you can open Flare, make all the changes you need, and then add any modified/deleted/new files to the commit list and commit them to the branch. You can commit as many times as you like, but these changes are still just local to your branch on your machine. We have an internal test site to which we can publish changes to verify how things look, but, as a matter of practice, we never publish to the public site from a working branch. If you switch back to the master (or any other) branch (again, I recommend closing Flare or any other editing tools in which your project files may be open when switching branches), you won't see any of the changes that you made in your other "working" branch. You can have several branches in progress at the same time, and each one is independent of the others.

For example, I may have one branch where I'm experimenting with some style changes, and another one where I'm adding a new topic on some new feature. While in the new topic branch, I won't see any of the style changes that I made in that style branch unless I decide to merge that style branch into my new topic branch, but I personally prefer not to do that unless I really need to. If you need to switch branches mid-stream, you'll need to commit (or stash, if you're not ready to commit) your changes before Git will allow you to switch. Otherwise, forcing a branch switch will cause you to lose all your uncommitted or unstashed changes.

Once you're satisfied with the changes in your branch and you've committed them, you can merge them into the master branch (again, best to have Flare closed), manually resolve any conflicts that Git couldn't resolve automatically (say someone else worked on one of the same files you did and merged their changes into the master after you created your branch, and Git can't tell whether to keep your changes, their changes, or both) using some kind of diff tool, and then push your changes to the server. That is the point at which they are no longer local to just your machine, and other people working on the project can now do a fetch or pull from the server to get the latest updates to the master branch. You should always do a fetch before merging and pushing, as Git won't allow you to push if your local copy of the master branch is "behind" the one on the server, meaning that someone else pushed changes after you last did a fetch and reset of the master branch. Finally, you can build and publish from the master to your public site.

While Git is a source control system, I also recommend using some other system that backs up your hard drive regularly, so that if things really go wrong, you have a way to restore to an earlier point. Once changes are pushed to the Git server, you can always restore from there, but while you're working on your own branch and haven't pushed, it's nice to know that you have a fallback.

That was a bit more long-winded than I intended, and of course, it's missing all the nitty-gritty of the actual commands, but hopefully it gives you an idea of the process and workflow. The point is that Git tracks everything for you, and Flare doesn't need to be involved. Whatever branch you're in, you simply work in Flare as usual, then close Flare, and go back to your Git interface to check the status, do your fetching, creating (of branches), adding (of new/changed/deleted files), committing, merging, and pushing.

If it helps, here is a screenshot of a series of commands to commit, merge, and push a change from a working branch to the master repository (note that I didn't do a fetch on the master branch before merging because I'm currently the only one working in this particular repository, so my local copy of master is always up-to-date):

GitWorkflow.png

[AnthonyD]

Rona!

That's an amazing response. It's going to take me a bit of time to go through. But thank you so much for putting it together!

I've already set up a meeting with our PM to get one of our devs tasked to helping me with this!

I'll let you know how we go.

Thanks!

[Rona Kwestel]

You're welcome, AnthonyD. Hopefully the developer is familiar with Git - that will help a lot - but feel free to ask questions here, and I'll answer as best as I can. There are plenty of online resources as well, and sometimes, when I can't remember a command, I just google around for it.

A couple of other points I should mention. We use BeyondCompare as our diff tool, and you can configure git to launch it automatically with a git command when you need to resolve a merge conflict, where Git will pull the base version of the file, your branch copy, and the local master copy, and open them all in different panes in the compare tool, but I confess that I find BC almost as confounding as Git itself, so if you have a tool you're comfortable with, use that.

Another thing to mention is that in general, the automatic merge done by Git is pretty reliable, but it's a good idea to check any tricky content like complicated tables just to make sure the merge was done correctly. Also, Git can only automerge text files; if you have any binary content, like Word docs, you'll have to merge that manually. My goal is to get rid of all our Word docs, but that will take some time.

Let us know how you 'git' on.