Skip to content

Loading…

Improvements to README and package.json #15

Closed
wants to merge 4 commits into from

3 participants

@myrne

Well, after diving into the code to see what it does to make up a proper description, I couldn't resist documenting what is happening a bit.

I hope you like the result.

I'm quite unfamiliar with filesystem stuff, so I may have described things not entirely correct, or just awkwardly. Nevertheless, I hope that with this "template" you can make it right quickly.

There's good stuff inside, so it must show on the outside!

@myrne

After I pushed to GitHub, I noticed I missed putting back-ticks around EAGAIN (last bullet point). And despite being very intrigued by it, I still don't understand how to use rebase as a "backspace" for history (as you put it on your blog).

@myrne

ping @isaacs .

@michaelficarra michaelficarra commented on an outdated diff
README.md
((4 lines not shown))
-Useful in asynchronous situations where one needs to try to open lots
-and lots of files.
+graceful-fs functions as a drop-in replacement for the fs module,
+making various improvements.
+
+The improvements are meant to normalize behavior across different
+platforms and environments, and to make filesystem access more
+resilient to errors.
+
+## Improvements over fs module
+
+* It keeps track of how many file descriptors are open, and by default

"It", "It", "It", "It", ...

@myrne
myrne added a note

Hey, it's an improvement over what's there, right? Otherwise, teach me how to use rebase, because I still don't get it. :)

No need to rebase.

  1. change file
  2. git add README.md
  3. git commit --amend
  4. git push --force

You shouldn't be working off of master, though.

Oh, I see that you already have 4 separate commits. In that case, just git rebase -i HEAD~4. Follow onscreen instructions and squash most recent 3 commits into earliest. When prompted, combine the commit messages into 1 message that makes sense. Force-push.

@myrne
myrne added a note

I actually like having separate commits. I think it's pretty descriptive. Still, looking at the rebase "interface" now (ran git rebase -i HEAD~4) it would seem doable.

What I'm gonna try instead is add a fifth commit with some fixes to the readme, then "squash" that with the fourth. That is a somewhat difficult way to do it compared to amend (which I'm a happy user of, through Tower.app) but it might prove to be my first successful encounter with rebase.

@myrne
myrne added a note

Hmm we're now discussing an outdated-diff. That's interesting.
First rebase of my career, woohoo! :dancer:

Thanks for helping me out, @michaelficarra .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@isaacs
Owner

Thanks! Landed (squashed) on b05d647.

For future reference, I'm almost always ok with multi-commit pulls, and I'll just squash them. Usually makes discussion easier, and you can always see the net result in the "Files Changed" tab on github.

@isaacs isaacs closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 12, 2013
  1. @myrne

    Improve package description.

    myrne committed
  2. @myrne

    Add some keywords.

    myrne committed
  3. @myrne
Commits on Apr 30, 2013
  1. @myrne

    A more descriptive readme.

    myrne committed
Showing with 44 additions and 7 deletions.
  1. +32 −4 README.md
  2. +12 −3 package.json
View
36 README.md
@@ -1,5 +1,33 @@
-Just like node's `fs` module, but it does an incremental back-off when
-EMFILE is encountered.
+# graceful-fs
-Useful in asynchronous situations where one needs to try to open lots
-and lots of files.
+graceful-fs functions as a drop-in replacement for the fs module,
+making various improvements.
+
+The improvements are meant to normalize behavior across different
+platforms and environments, and to make filesystem access more
+resilient to errors.
+
+## Improvements over fs module
+
+graceful-fs:
+
+* keeps track of how many file descriptors are open, and by default
+ limits this to 1024. Any further requests to open a file are put in a
+ queue until new slots become available. If 1024 turns out to be too
+ much, it decreases the limit further.
+* fixes `lchmod` for Node versions prior to 0.6.2.
+* implements `fs.lutimes` if possible. Otherwise it becomes a noop.
+* ignores `EINVAL` and `EPERM` errors in `chown`, `fchown` or
+ `lchown` if the user isn't root.
+* makes `lchmod` and `lchown` become noops, if not available.
+* retries reading a file if `read` results in EAGAIN error.
+
+On Windows, it retries renaming a file for up to one second if `EACCESS`
+or `EPERM` error occurs, likely because antivirus software has locked
+the directory.
+
+## Configuration
+
+The maximum number of open file descriptors that graceful-fs manages may
+be adjusted by setting `fs.MAX_OPEN` to a different number. The default
+is 1024.
View
15 package.json
@@ -1,7 +1,7 @@
{
"author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me)",
"name": "graceful-fs",
- "description": "fs monkey-patching to avoid EMFILE and other problems",
+ "description": "A drop-in replacement for fs, making various improvements.",
"version": "1.2.0",
"repository": {
"type": "git",
@@ -19,10 +19,19 @@
},
"keywords": [
"fs",
- "EMFILE",
+ "module",
+ "reading",
+ "retry",
+ "retries",
+ "queue",
"error",
+ "errors",
"handling",
- "monkeypatch"
+ "EMFILE",
+ "EAGAIN",
+ "EINVAL",
+ "EPERM",
+ "EACCESS"
],
"license": "BSD"
}
Something went wrong with that request. Please try again.