A micro-framework for observing file changes, both local and remote. Helpful in building developer tools.

Related tags



Demo GIF

CI Status Version License Platform

Wouldn't it be great if we could adjust feeds and configurations of our native apps without having to sit back to Xcode, change code, recompile and navigate back to screen we were at?

One of the basis of building tools that allow us to do just that is the way we observe for data changes, this micro-framework provides you File observers for Local and Remote assets.

This framework provides:

  • FileWatcher.Local useful for observing local file changes, it can also be used to breach Sandbox env for debug simulator builds and e.g. observe file on the developer desktop (like the demo app does).

  • FileWatcher.Remote can be used to observe files on the web, it supports both Etag headers and Last-Modified-Date so you can just put file on Dropbox or real ftp server.

It also supports usage from Objective-C projects. For this, you should consider these following steps:

  1. Add $(TOOLCHAIN_DIR)/usr/lib/swift/$(PLATFORM_NAME) into your projects Library Search Paths in Build Setting section.

  2. Import swift-header by adding @import KZFileWatchers; into any .m file, where you want to use FileWatchers.

  3. Use provided classes for set up file observing like this:

self.fileWatcher = [[LocalFileWatcher alloc] initWithPath:path];
self.fileWatcher.delegate = self;
[self.fileWatcher startWithError:nil];
  1. Implement FileWatcherDelegate in your class for handling file refreshing events. For example:
- (void)refreshDidOccurFrom:(id<FileWatcherProtocol>)fileWatcher type:(enum RefreshResult)type data:(NSData *)data
    self.textLabel.text = [[NSString alloc] initWithData:data encoding:kCFStringEncodingUTF8];


KZFileWatchers is available through CocoaPods and Swift Package Manager.


In order to install KZFileWatchers by using CocoaPods, simply add the following line to your Podfile:

pod "KZFileWatchers"

Last version to support Swift 2.3 is 0.1.2 Last version to support Swift 3.0 is 1.0.4

Swift Package Manager

Installing KZFileWatchers over SwiftPM is only supported since version 1.0.1. You just need to add it as a dependency to your Package.swift manifest:

import PackageDescription

let package = Package(
    name: "YourTarget",
    dependencies: [
        .Package(url: "https://github.com/krzysztofzablocki/KZFileWatchers.git", majorVersion: 1),


Krzysztof Zabłocki, [email protected]


Contributions to KZFileWatchers are welcomed and encouraged! Please see the Contributing guide.

A list of contributors is available through GitHub.

To give clarity of what is expected of our members, KZFileWatchers has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities. For more, see the Code of Conduct.


KZFileWatchers is available under the MIT license. See LICENSE for more information.

  • Objc Interoperability

    Objc Interoperability

    Hi, I want to add interoperability with Objective-C by writing some wrappers above classes and enum, without modifying original sources. It could be useful for project with legacy code base.

    opened by morzv 6
  • TextEdit is breaking the dispatch_source observation

    TextEdit is breaking the dispatch_source observation

    Hi there, Thanks for this project. I am trying this out at present but I am not sure how it works.In the sample source example ,when I run the app and open the text file the changes that are typed in the text file are reflected on the app only when the file is saved . This happens only the first time , rest of the time if I change the text and save again nothing gets changed. This is contrary to what is happening in the GIF that has been attached to the project. Please tell tell how to make sure it works that way.

    opened by uutkarshsingh 5
  • [Question] KZFileWatchers Fatal Error, Xcode 8.2.1, Swift 3.0.2

    [Question] KZFileWatchers Fatal Error, Xcode 8.2.1, Swift 3.0.2

    Hi, from New Zealand! :-)

    I like the idea of this framework and hopefully will be using it in an app I am developing, along with Freddy (for JSON data), and ReSwift (reactive states).

    I downloaded this repo on 20 April 2017, and put only the source files into my project.

    Recently, I have had a fatal runtime error on this piece of code in the Daemon class: try! fileWatcher.start(closure: { result in

    The full error is this: fatal error: 'try!' expression unexpectedly raised an error: trips.FileWatcher.Error.failedToStart("Failed to open file"): file /Library/Caches/com.apple.xbs/Sources/swiftlang/swiftlang-800.0.63/src/swift/stdlib/public/core/ErrorType.swift, line 178

    As seen in this screenshot of Xcode: http://imgur.com/a/cVQZT

    I have adapted the Daemon code to initialize with an URL, then pass that as a path String to FileWatcher.Local as: fileWatcher = FileWatcher.Local(path: String(describing: jsonURL))

    This is shown by the full URL (where 'Store' and 'state.trip' both exist): file:///Users/mikenorman/Library/Developer/CoreSimulator/Devices/72D4C7B2-B12E-4E0D-B520-A194237BCABA/data/Containers/Data/Application/FCA0A655-5F08-40C9-AAF4-0658C8346439/Library/Store/state.trip

    I am currently testing this to the iPhone 6s Simulator, which is working fine for any other builds. The file I am trying to 'watch' is a JSON file (state.trip) in a 'Store' folder in the app's Library folder.

    Is this an invalid operation for the i386 architecture? I only want to use this on iOS. Thread 1: EXC_BAD_INSTRUCTION (code=EXC_i386_INVOP, subcode=0x0)

    I am not sure why it is throwing that fatal error, and any help will be awesome.



    opened by ghost 4
  • Added SwiftPM support

    Added SwiftPM support

    Adding SwiftPM support for https://github.com/krzysztofzablocki/Sourcery/issues/28 requires KZFileWatchers to support it too.

    If you want, I can add SwiftPM as additional installation method to your README.md. As SwiftPM currently doesn't support iOS, shall I just add swift build to .travis.yml? This would at least ensure, that the Package.swift file format is correct.

    In order to finish support for SwiftPM, you need to schedule a new release and tag.

    opened by vknabel 3
  • Add objective-c interoperability

    Add objective-c interoperability

    I added some wrappers above swift enum and classes for using it from Objective-C code.

    opened by morzv 2
  • Support newest Xcode & Swift

    Support newest Xcode & Swift

    Hi, I would like to update the project to Xcode 9.3 and Swift 4.1. I would love to make PR but firstly I want to hear if this change is wanted or not. I noticed that used pods versions are very old and that some small code improvements can be done.

    opened by tomassliz 2
  • Swift3


    Updated dependencies, framework, tests and example project

    opened by IanKeen 2
  • Carthage support

    Carthage support

    opened by TofPlay 2
  • fix: detect changes made by vim

    fix: detect changes made by vim

    After the change made to fix #2, changes made by vim and MacVim aren't detected. This fix is arguably hack-ish — it involves a one-time retry with a delay when we can't find the file to restart observing —, but given how vim seems to do this strange thing where saving a file seems to be delete it and then created the replacement with the same filename..

    Note that with this retry, there's this strange behaviour (supposedly due to how vim works):

    1. Save file in MacVim
    2. Changes get detected, this can continue to work a few times ...
    3. Save file in MacVim
    4. Can't find file to restart restart observing
    5. Retry once, look for the file to restart observing
    6. Changes gets detected correctly

    There's a strange pause of a few seconds between 5-6. If you switch away from vim (if in Terminal) or in MacVim.app, it resumes immediately.

    I'd be happy if there's a better way to make this work for vim/MacVim though :)

    opened by hboon 1
  • Small fixes.

    Small fixes.

    opened by lkuczborski 1
  • Optimize Remote Watching

    Optimize Remote Watching

    use HEAD http request to compare meta changes instead of downloading for every interval.

    opened by ninokierulf 1
  • FTP support

    FTP support

    Hey there I want to connect a real FTP address with user:pass in xcode 9, can be use your framework?

    Like this url.

    enhancement help wanted 
    opened by Saleh-At 3
Krzysztof Zabłocki
Dev, Speaker, Creator. Currently Lead iOS @NYTimes My code powers up more than 70 000 apps.
Krzysztof Zabłocki
zip file I/O library for iOS, macOS and tvOS

ZipZap is a zip file I/O library for iOS, macOS and tvOS. The zip file is an ideal container for compound Objective-C documents. Zip files are widely

Glen Low 1.2k Aug 18, 2021
Simple and expressive file management in Swift

Installation • Usage • License • Documentation FileKit is a Swift framework that allows for simple and expressive file management. Development happens

Nikolai Vazquez 2.2k Sep 17, 2021
Effortless ZIP Handling in Swift

ZIP Foundation is a library to create, read and modify ZIP archive files. It is written in Swift and based on Apple's libcompression for high performa

Thomas Zoechling 1.7k Sep 18, 2021
Swift framework for zipping and unzipping files.

Zip A Swift framework for zipping and unzipping files. Simple and quick to use. Built on top of minizip. Usage Import Zip at the top of the Swift file

Roy Marmelstein 2.1k Sep 17, 2021
ZipArchive is a simple utility class for zipping and unzipping files on iOS, macOS and tvOS.

SSZipArchive ZipArchive is a simple utility class for zipping and unzipping files on iOS, macOS and tvOS. Unzip zip files; Unzip password protected zi

ZipArchive 4.9k Sep 17, 2021