├── docs ├── changelog.md ├── faq.md └── getting_started.md └── README.md /docs/changelog.md: -------------------------------------------------------------------------------- 1 | Changelog 2 | ========= 3 | 4 | 1.1.0 - December 11, 2020 5 | 6 | * Moved each discovered diff to its own section. Hide unimportant/unaffected files by default. 7 | 8 | 1.0.10 - August 19, 2020 9 | 10 | * Fixed table ID issue. 11 | 12 | 1.0.8 - March 20, 2020 13 | 14 | * Fixed serious data corruption bug on manual file location changes. 15 | 16 | 1.0.6 - November 22, 2019 17 | 18 | * Various improvements, particularly to checkboxes. 19 | 20 | 1.0.4 - October 3, 2019 21 | 22 | * Fixed multiple SSH host issue. Fixed SSH editing message. 23 | 24 | 1.0.0 - October 2, 2019 25 | 26 | * Initial release. 27 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | File Tracker 2 | ============ 3 | 4 | The world's first cross-platform, bulk visual diff/merge tool. Massively deploy and synchronize changes/updates across multiple software projects and systems in minutes instead of days or weeks. 5 | 6 | [![File Tracker Overview and Tutorial video](https://file-tracker.cubiclesoft.com/file_cache/18139/filetracker_overview_tutorial_video.920.png)](https://www.youtube.com/watch?v=1DSwPnEf308 "File Tracker Overview and Tutorial") 7 | 8 | File Tracker is a tool that safely and easily speeds up global updates of software changes of thousands of files across hundreds of projects and systems. The result typically pays off thousands of man-hours of technical debt per team member in just a few hours with the first use (i.e. it pays for itself). Since it is a very hands-on tool, using it is less error-prone and therefore less likely to break existing software projects than to do the same work manually. 9 | 10 | CubicleSoft File Tracker is commercial, non-free software. [Purchase a File Tracker license](https://file-tracker.cubiclesoft.com/) to obtain the software. 11 | 12 | This repository contains official product documentation and issue tracking of bugs and features. 13 | 14 | Documentation 15 | ------------- 16 | 17 | * [Getting Started Guide](docs/getting_started.md) 18 | * [Frequently Asked Questions](docs/faq.md) 19 | * [Changelog](docs/changelog.md) 20 | 21 | Product Support 22 | --------------- 23 | 24 | Creating issues on the issue tracker for this repository is limited to collaborators. That is, only CubicleSoft can open new issues. To obtain product support, please login to the [Product Support Center](https://file-tracker.cubiclesoft.com/product-support/). 25 | 26 | If an issue on the issue tracker is opened regarding your support request, you'll be notified and then you and/or members of your team will be able to subscribe to notifications to watch the progress of the issue. 27 | -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | Frequently Asked Questions 2 | ========================== 3 | 4 | The following are a series of frequently asked questions and the answers to those questions grouped by category. 5 | 6 | Pre-Purchase 7 | ------------ 8 | 9 | **What is File Tracker?** 10 | 11 | If you've ever used [Beyond Compare](https://www.scootersoftware.com/) or [Meld](https://meldmerge.org/) or [KDiff3](http://kdiff3.sourceforge.net/), then you know what those tools are capable of...and their obvious limitations. 12 | 13 | File Tracker is a bulk visual diff/merge tool. It performs visual diff/merges with one source file to many destination files. It can modify thousands of files, massively commit and push to upstream version control repositories, and synchronize changes across SSH hosts. Any file in a collection of files (known as a File Group within File Tracker) can be chosen as the "source file," which defaults to the most recently modified version of a file to save time selecting the source file. It also has a very fast system scanner with support for scanning and updating remote systems over SSH. 14 | 15 | **Who is this product for?** 16 | 17 | File Tracker is for any software developer or development team that manages common code shared across multiple projects. Where "multiple projects" is a minimum of around 20 projects. 18 | 19 | Let's say a specific file contains a security vulnerability. The first step is to patch the library where that file is used. The next step is to deploy the patched library to all locations where the library is used. However, to safely upgrade an application with the patched file, the existing file needs to be compared to make sure that updating the file won't cause the application to break. Repeat ad nauseum for each instance of the file. And then repeat that ad nauseum for each file. 20 | 21 | It can take hours to days to deploy a single change for one file let alone modifying changes of files at scale. This leads to accumulating extensive technical debt by not deploying updates across projects in a timely fashion. As a result, projects tend to end up with different versions of the same set of files that slowly becomes unmanageable. 22 | 23 | File Tracker makes short work of the entire process and wipes out technical debt by being able to safely and confidently deploy changes across an unlimited number of projects on an unlimited number of hosts in minutes instead of hours, days, or even weeks. 24 | 25 | **What does the license cover?** 26 | 27 | A single license covers you and/or your whole team plus upgrades and product support for one year. 28 | 29 | **What's the latest version of File Tracker?** 30 | 31 | The [CubicleSoft File Hashes repository](https://github.com/cubiclesoft/product-hashes) tracks product hashes and version information about the latest releases of File Tracker. 32 | 33 | The [Changelog](docs/changelog.md) tracks high-level changes across the product. It's not particularly complete and the earliest notes are from tracking in an internal git repo. 34 | 35 | **Is there a demo/shareware version?** 36 | 37 | Nope. Sorry. Please use the [Getting Started Guide](docs/getting_started.md), the Overview Tutorial video, and the questions and answers here in the FAQ to make your decision about whether or not File Tracker is right for you. If the previous questions are bringing up old memories, then there's been a lot of wasted time on a problem that File Tracker solves. 38 | 39 | Post-Purchase 40 | ------------- 41 | 42 | **Okay, I've bought a license, now what?** 43 | 44 | Follow the [Getting Started Guide](docs/getting_started.md). 45 | 46 | If you encounter any difficulties, reach out on the Help/Support channel. File Tracker is a bit complex and can seem a little scary the first time it makes a ton of VCS commits and pushes, so don't be afraid to ask questions. 47 | 48 | **How do I undo a major mistake?** 49 | 50 | Hope you keep good backups. Just kidding. But you really should keep good backups. 51 | 52 | If you haven't Synchronized yet, simply clear all of the scheduled changes for the Projects/Files. 53 | 54 | If you have Synchronized, then restoring from a backup or using standard version control mechanisms to locate a previous version of the file and just restoring one file can get you back on the right track. After manually restoring one file in one project, follow the usual File Tracker workflow to deploy the previous file across all projects, but make sure to select the older file as the source. That will at least get you back to the previous state. 55 | 56 | **How can I handle advanced git setups?** 57 | 58 | The git distributed version control system (DVCS) is extremely complex. It has submodules, branches, tags, history rewriting, forking/pulling, and more. The File Tracker VCS support is generic. It supports many different version control systems, which means git-specific features may be more difficult to configure. 59 | 60 | For really complex setups where a single directory tree contains multiple git repos inside git repos, using the Manual file selection option in a Project is useful if only slightly more tedious. If you are having issues planning out your Project setup/layout, feel free to reach out on the Help/Support channel. 61 | 62 | **How to handle password-protected SSH keys with git?** 63 | 64 | Unfortunately, you'll have to push to your origin(s) manually. There are some limitations with the underlying SSH library. 65 | 66 | Feel free to reach out on the Help/Support channel though for possible solutions. 67 | 68 | **How do I share my configuration/File Groups/Project setup with the rest of my team?** 69 | 70 | You just spent two hours configuring File Tracker and using it for the first time to make 220 commits across 43 different projects. Now the rest of your team wants to use it too. 71 | 72 | At the moment, the only thing that can be shared is the entire File Tracker database and maybe the configuration settings. That option may or may not work for you/your team. 73 | 74 | Sharing is definitely one of the weaker areas of File Tracker. Keep in mind though that without File Tracker, it would take weeks to months of time to accomplish the same activities. However, let's discuss your complex sharing needs on the Help/Support channel. 75 | 76 | **What's the refund policy?** 77 | 78 | File Tracker is somewhat complex to figure out, so it's entirely likely that you just need a little help for your particular use-case. 79 | 80 | However, if File Tracker isn't to your liking or just isn't working out, simply ask nicely for a refund. 81 | 82 | Feel free to reach out on the Help/Support channel for either option. 83 | -------------------------------------------------------------------------------- /docs/getting_started.md: -------------------------------------------------------------------------------- 1 | Getting Started Guide 2 | ===================== 3 | 4 | The overview/tutorial video contains some slightly outdated information due to some screens changing but still provides good coverage of what to expect: 5 | 6 | [![File Tracker Overview and Tutorial video](https://file-tracker.cubiclesoft.com/file_cache/18139/filetracker_overview_tutorial_video.920.png)](https://www.youtube.com/watch?v=1DSwPnEf308 "File Tracker Overview and Tutorial") 7 | 8 | Installation 9 | ------------ 10 | 11 | To install the product, login to the [Product Support Center](https://file-tracker.cubiclesoft.com/product-support/) and download the latest version from there. 12 | 13 | A current license of the software grants access to the installers for Windows, Mac OSX, and Linux. 14 | 15 | During the first run of the software, it will ask for license information. Enter the license information and save it. After that, entering the Product Support Center in the future is as simple as clicking "Help/Support" from within File Tracker itself. 16 | 17 | Available upgrades are automatically detected by File Tracker when it starts up. To upgrade the software, visit the Product Support Center, download the update, then make sure File Tracker is completely stopped, and finally install the upgrade. 18 | 19 | Configuration 20 | ------------- 21 | 22 | After installation, the next step is to configure the scanner. Under Edit Configuration, enter file paths on the local system to scan, set local version control environment variables, etc. 23 | 24 | ![File Tracker configuration](https://cubiclesoft.com/files/18093/filetracker_screenshot_edit_config.png) 25 | 26 | For any remote SSH systems, set up SSH keys and connection profiles. Each connection profile has configuration options similar to those found in Edit Configuration. Be sure to click "Deploy Remote" to deploy the remote software to the host so that the scanner will function. 27 | 28 | Under Manage Files, set up the first File Group. 29 | 30 | ![Managing file groups](https://cubiclesoft.com/files/18139/filetracker_screenshot_manage_files.png) 31 | 32 | A file group is a collection of one or more files that are identical or nearly identical (e.g. a slightly different intro). The goal of a file group is to keep all files within the group in relative sync with other files in the group and also predefines some things like a common commit message to use when File Tracker interacts with version control software. A file group could consist of library files, support files, or even files spanning an entire application. File groups can be differentiated by only including a file if it matches a specific string (e.g. the business name). 33 | 34 | When using File Tracker for the first time, configuring just one File Group is recommended. 35 | 36 | Workflow 37 | -------- 38 | 39 | Once a File Group has been configured, File Tracker has a primary workflow cycle of: 40 | 41 | * Find matching files (Synchronize) 42 | * Adjust configuration as needed (Edit Configuration or Manage SSH Profiles) 43 | * Adjust projects as needed (Manage Projects) 44 | * Process files (Manage Files) 45 | * Process commits and pushes (Manage Projects) 46 | * Push out scheduled changes (Synchronize) 47 | 48 | This workflow generally traverses the first three menu items and then back with rare stops at the configuration. 49 | 50 | The first Synchronize operation is the slowest because it will most likely scan the entire directory tree. After the first scan completes, take note of any "Slow paths" that were detected. These are the paths of the directory tree that returned no file group matches but took the longest to scan. If there are no future file groups down a particular part of the directory tree, then the paths can be added to the "Exclude Directories" list and the scanner will skip scanning that part of the directory structure during the next scan. Many Synchronize system scans can generally be reduced from minutes to just a few seconds by adding some carefully selected exclusion paths. Getting scan times reduced up front is worth the effort later on. 51 | 52 | The Manage Projects portion of File Tracker allows for setting up automatic version control integration (git, svn, etc.) and grouping collections of files into logical projects. Checking for files not assigned to a project is a good idea to do after every Synchronize operation. Assign found files to projects before moving onto Manage Files. 53 | 54 | Manage Files shows up to three major sections: 55 | 56 | * Needs Processing 57 | * Ready For Sync 58 | * Nothing To Do 59 | 60 | File Groups in the "Needs Processing" section appear there due to at least one of three different conditions: 61 | 62 | * New files detected 63 | * Removed files detected 64 | * Maximum version count threshold for the File Group was exceeded 65 | 66 | For the first scan, it is usually desireable to choose a specific file to move to the top of the list of files for the File Group. For example, a library file might have a source project for that file. Going into "Locations," locating the file, editing selecting "Options", setting "Move To Top" to "Yes", and then saving the configuration for the file. 67 | 68 | File Tracker is actually a pseudo-merge tool. Unlike traditional visual diff/merge tools, it's designed for making bulk changes, not one-offs. In general, it will preserve the newline style of the target system for non-binary files (e.g. DOS/Windows vs. Linux line endings). However, it can also preserve portions of files that it updates and/or apply string replacements. These advanced features allow for near-identical copies of individual files within a File Group to be carefully preserved. 69 | 70 | After adjusting per-file configurations in the files that are attached to the File Group, enter the "Process Diffs" section. This section of File Tracker determines a file source, generates and shows diffs based on the file source, and determines the most plausible course of action to take by default. However, every action can be manually overridden. Also keep in mind that changes are not applied to any files until the next Synchronize operation takes place. 71 | 72 | Once "Process Diffs" has been completed, the File Group will move to the "Ready For Sync" section. Once all desired File Groups have been processed, return to Manage Projects. Here, commits and pushes can be applied. If all looks good, go to the bottom of the page and click the "Save" button. 73 | 74 | The final step of the workflow is to return to the Synchronize screen and run a Synchronize operation. All scheduled changes are made, commits and pushes to repositories are made, and a file scan is conducted. 75 | 76 | The workflow should be repeated until all desired File Groups have reached the "Nothing To Do" state. Note that setting a higher minimum unique version threshold may be required for some situations to get the File Group to change to the "Nothing To Do" state. 77 | 78 | File Tracker leaves all changes in the hands of the user. There is no one-size-fits-all solution that can be automated because, as you'll discover, each File Group has its own quirks that almost inevitably results in manual intervention on occasion. 79 | 80 | Making Backups 81 | -------------- 82 | 83 | It's always important to make good backups (e.g. the 3-2-1 rule). Setting up File Tracker can represent a time investment of several hours. Therefore, being able to preserve configuration, Project, and File Group settings when moving or restoring a system saves a lot of time. 84 | 85 | Most backup software defaults to backing up and restoring the user's home directory. This is, in general, good enough unless you are a software developer. Software devs tend to do their own thing and not use the OS manufacturer-recommended per-user data storage mechanisms, especially on Windows. 86 | 87 | The File Tracker SQLite database and configuration are stored at the following locations on various OSes: 88 | 89 | * Windows - %LOCALAPPDATA%\CubicleSoft\File Tracker 90 | * Mac OSX and Linux - %HOME%/.config/CubicleSoft/File Tracker 91 | 92 | Be sure to add the relevant path to your backup software. 93 | --------------------------------------------------------------------------------